Skip to content

Commit

Permalink
Update the 'Getting started' page
Browse files Browse the repository at this point in the history
  • Loading branch information
aarondettmann committed Jun 10, 2020
1 parent 42c1b6d commit 75ce1c0
Show file tree
Hide file tree
Showing 3 changed files with 47 additions and 17 deletions.
8 changes: 5 additions & 3 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,10 @@ To update an existing installation, run:
pip install --upgrade framat
Getting started
---------------

If you have installed FramAT, you may want to have a look at the `Getting started <https://framat.readthedocs.io/en/latest/user_guide/getting_started.html>`_ page.

Example
-------
Expand Down Expand Up @@ -86,9 +90,7 @@ FramAT provides a user-friendly, easy-to-read Python interface which can be inte
model.run()
Please refer to the documentation for installation instructions and a user guide:

* https://framat.readthedocs.io/
Please refer to the `documentation <https://framat.readthedocs.io/>`_ for more information.

Additional information for developers
-------------------------------------
Expand Down
21 changes: 9 additions & 12 deletions docs/source/user_guide/getting_started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Getting started
===============

This page briefly explains how to get started with |name|. The goal is to give you a basic understanding of how |name| works and how analyses can be set up and run. We also explain how to fetch result data which may be of interest to you. Please note that the model interface and all available model and result parameters are explained in more detail on the following pages.
This page briefly explains how to get started with |name|. The goal is to give you a basic understanding of how |name| works, and how analyses can be set up and run. We also explain how to fetch result data which may be of interest to you. Please note that the model interface and all available model and result parameters are explained in more detail on the following pages.

Python API
----------
Expand All @@ -13,13 +13,13 @@ Python API
Built-in models
---------------

|name| includes a number of built-in models. The simplest model is a single cantilever beam loaded with a point load at the free end. First, create a Python script (or download the script from the link below) and run it with ``python example_cantilever.py``.
|name| includes a number of built-in models which allows you to run a full beam analysis with only a few lines of code. The simplest model is a single cantilever beam loaded with a point load at the free end. First, create a Python script (or download the script from the link below) and run it with ``python example_cantilever.py``.

**Download:** `example_cantilever.py <https://raw.githubusercontent.com/airinnova/framat/master/tests/integration/getting_started_models/example_cantilever.py>`_

.. literalinclude:: ../../../tests/integration/getting_started_models/example_cantilever.py
:language: python

**Download the script:** `example_cantilever.py <https://raw.githubusercontent.com/airinnova/framat/master/tests/integration/getting_started_models/example_cantilever.py>`_

When running the script from a terminal you should see a few log entries providing feedback about the program status, and an interactive plot should be created displaying the beam model.

.. figure:: ../../../tests/integration/getting_started_models/example_cantilever.png
Expand All @@ -29,22 +29,21 @@ When running the script from a terminal you should see a few log entries providi

Simple built-in cantilever model

This example is, admittedly, not the most exciting model, but it allows you to easily check that |name| has been installed correctly on your system and works. Note that you can try to run some other (more exciting) built-in models. Just replace ``'cantilever'`` with one of the following strings.
This example is, admittedly, not the most exciting model, but it allows you to easily check that |name| has been installed correctly on your system and works. Note that you can try to run some other (perhaps more exciting) built-in models. Just replace ``'cantilever'`` with one of the following strings.

.. include:: ../builtin_models.txt

Building your own model
-----------------------

Let's now explore a few more options to give you an overview of how to actually set up you own model.
Now, let's explore a few more options to give you an overview of how to actually set up and run your *own* model. We do not go through all features that are available to you. We only show the most basic features, but if you understand the following example you will be able to easily make use of the other features which are documented on the next pages. As with the previous example we highly encourage you to try it out yourself. Just download the script and run it. Make sure to read the comments in the script and play around with the script to get a feel for how |name| works.

**TODO**
**Download:** `example_model2.py <https://raw.githubusercontent.com/airinnova/framat/master/tests/integration/getting_started_models/example_model2.py>`_

.. literalinclude:: ../../../tests/integration/getting_started_models/example_model2.py
:language: python

**Download the script:** `example_model2.py <https://raw.githubusercontent.com/airinnova/framat/master/tests/integration/getting_started_models/example_model2.py>`_

When running the script above you should the following plot.

.. figure:: ../../../tests/integration/getting_started_models/example_model2.png
:width: 500 px
Expand All @@ -53,9 +52,7 @@ Let's now explore a few more options to give you an overview of how to actually

Example model

**TODO**

Fetching result data
--------------------

**TODO**
Whenever you perform a new analysis, you will use the ``model.run()`` method. This function will always return a results object which behaves very much like the model object itself. All available result data is fully documented on the following pages.
35 changes: 33 additions & 2 deletions tests/integration/getting_started_models/example_model2.py
Original file line number Diff line number Diff line change
@@ -1,40 +1,71 @@
# The Model object is used to set up the entire structure model, and to run a
# beam analysis
from framat import Model

# Create a new instance of the Model object
model = Model()

# ===== MATERIAL =====
# Create a material definition which can be referenced when creating beams.
# Note that you can add as many materials as you want. Just provide a different
# UID (unique identifier) for each new material. Below we define the Young's
# modulus, the shear modulus and the density.
mat = model.add_feature('material', uid='dummy')
mat.set('E', 1)
mat.set('G', 1)
mat.set('rho', 1)

# ===== CROSS SECTION =====
# Besides material data, we also need cross section geometry, or more
# specifically, the cross section area, the second moments of area, and the
# torsional constant.
cs = model.add_feature('cross_section', uid='dummy')
cs.set('A', 1)
cs.set('Iy', 1)
cs.set('Iz', 1)
cs.set('J', 1)

# ===== BEAM =====
# Next, let's add a beam! We define the geometry using "named nodes", that is,
# we provide the coordinates of some "support nodes" which can be referred to
# with their UIDs.
beam = model.add_feature('beam')
beam.add('node', [0.0, 0, 0], uid='a')
beam.add('node', [1.5, 0, 0], uid='b')
beam.add('node', [1.5, 3, 0], uid='c')
beam.add('node', [0.0, 3, 0], uid='d')
# Set the number of elements for the beam.
beam.set('nelem', 40)
# Set the material, cross section and cross section orientation
beam.add('material', {'from': 'a', 'to': 'd', 'uid': 'dummy'})
beam.add('cross_section', {'from': 'a', 'to': 'd', 'uid': 'dummy'})
beam.add('orientation', {'from': 'a', 'to': 'd', 'up': [0, 0, 1]})

# Add some line loads [N/m] and point loads [N]
beam.add('distr_load', {'from': 'a', 'to': 'b', 'load': [0, 0, -2, 0, 0, 0]})
beam.add('distr_load', {'from': 'c', 'to': 'd', 'load': [0, 0, -2, 0, 0, 0]})
beam.add('distr_load', {'from': 'b', 'to': 'c', 'load': [0, 0, 1, 0, 0, 0]})
beam.add('point_load', {'at': 'b', 'load': [+0.1, +0.2, +0.3, 0, 0, 0]})
beam.add('point_load', {'at': 'c', 'load': [-0.1, -0.2, -0.3, 0, 0, 0]})

# ===== BOUNDARY CONDITIONS =====
# We also must constrain our model. Below, we fix the nodes 'a' and 'd'
bc = model.set_feature('bc')
bc.add('fix', {'node': 'a', 'fix': ['all']})
bc.add('fix', {'node': 'd', 'fix': ['all']})

# ===== POST-PROCESSING =====
# By default the analysis is run without any GUI, but to get a visual
# representation of the results we can create a plot
pp = model.set_feature('post_proc')
pp.set('plot_settings', {'show': True})
pp.add('plot', ['undeformed', 'deformed', 'node_uids', 'nodes', 'forces'])

model.run()
# Run the beam analysis
results = model.run()

# ===== RESULTS =====
# The result object contains all relevant results. For instance, we may fetch
# the global load vector.
load_vector = results.get('tensors').get('F')
print(load_vector)
...

0 comments on commit 75ce1c0

Please sign in to comment.