# Solid Mechanics Group Wiki This wiki is a place to collect general guidance for members of the Solid Mechanics Research Group. This is the place to collect and organize reference material: how to get started, how to use group computing resources, how to organize research output, and how to navigate common student processes. {% hint style="info" %} Group members who need to edit this wiki should sign in at [GitBook](https://app.gitbook.com/). After signing in, open the Solid Mechanics Group wiki in the editor. You can also edit the Github repo directly at {% endhint %} ## New to the group? [Mike's Research Guide](/research-practices/student-research-guide) is a great place to start. # Reaching Out About Research This page gives advice for students who want to contact a professor about joining a research group as an undergraduate researcher or graduate research assistant. ## Before You Email Narrow your list to a few faculty members whose research genuinely interests you. This takes time: read websites, browse recent publications, and identify the faculty member's main research interests, applications, and methods. Do not send form emails. Faculty can usually identify them quickly, and they rarely stand out. ## Writing the Email Use professional writing and courtesy. Keep the message brief, specific, and direct. Good emails usually include: * A concise statement of who you are * Why you are interested in that specific research group * What kind of work interests you: theory, computation, experiment, application area, methods, or tools * Your goals for the research position * Your CV, transcript if appropriate, and other useful application materials Avoid: * Flattery * Long generic introductions * Claims that you deeply understand papers you have only skimmed * Questions that are already answered on the faculty member's website * Messages focused only on how the appointment would benefit you ## Reading Publications Use publications to learn what the group does, not to show off. Browse recent papers, abstracts, and figures to understand research directions. It is fine if you do not understand everything; academic papers often take years of background to fully digest. ## Be Specific Before reaching out, be able to answer: * Are you interested in theory, computation, experiment, or a combination? * Do you want hands-on work, abstract modeling, code development, data analysis, or something else? * Are your interests consistent with the group's actual work? * Are you seeking undergraduate experience, a PhD position, a postdoc, or another role? Research appointments should be mutually beneficial to the student and the faculty member. A focused message makes that fit easier to evaluate. # Assignment Zero Graduate-level research requires independent thinking and the ability to solve open-ended or underconstrained problems. ## Overview The purpose of this assignment is to give you experience solving research-like problems and to help you determine whether graduate-level research in computational solid mechanics is a good fit. Everything needed to complete this project is available, but it is up to you to figure it out. There are only two rules: 1. No plagiarism. 2. You may not ask Dr. Runnels for help. ## Assignment Statement {% hint style="success" icon="map-pin" %} **Compute the energy and structure of a grain boundary in an FCC material using molecular dynamics. Present your results in a report written in LaTeX. The report does not need to be long, but it should be written in proper scientific style, contain publication-quality figures, and cite relevant sources.** {% endhint %} ## Pointers * LAMMPS is a free, open-source molecular dynamics simulation package. * OVITO is useful for visualizing atomic structures. * LaTeX is document processing software. Overleaf is an online LaTeX platform. Depending on your prior experience, this project can take as little as a few hours or as long as a few weeks. Good luck! # Termin Termin is our group project management software, accessible at termin.solids.group. Termin is the Solid Mechanics Group's project management system. It is designed for academic work, where one person may be coordinating research projects, papers, students, classes, proposals, reviews, travel, and administrative tasks at the same time. Use Termin for work that needs to be tracked, assigned, discussed, or revisited. It is especially useful when a task has an owner, a due date, a dependency, a collaborator, or a record of discussion that should not disappear into email or chat. {% hint style="info" %} Termin is available at [termin.solids.group](https://termin.solids.group). Use your group account or a connected Google, GitHub, or Microsoft account if those login options have been enabled for you. {% endhint %} ## :solid:The Basic Model Termin is organized around a few core objects:
:solid:ProjectsLarge units of work, such as a paper, code project, proposal, student research effort, class, or administrative responsibility.
:solid:GroupsSubsections inside a project. Groups are useful for milestones, paper sections, experiment batches, class modules, or categories of related tasks.
:solid:TasksSpecific work items. Tasks can have due dates, assignees, status modes, descriptions, comments, links, attachments, prerequisites, and calendar behavior.
:solid:TeamsReusable sets of people. Teams can be invited to Termin and shared onto projects so that access management does not have to be repeated one user at a time.
:solid:Direct SpacesOne-on-one spaces for work shared between two people. These are useful for advisor-student task lists, private follow-up, and lightweight direct collaboration.
The most important habit is to put work in the smallest useful container. A paper should usually be a project. Major paper components can be groups. Individual actions should be tasks. ## :solid:Main Views Termin has two main working views.
:solid:TreeThe structured project view. Use this when creating projects, arranging groups, editing task details, reviewing discussions, moving work around, or planning a project from top to bottom.
:solid:TodoThe personal action view. Use this when deciding what to do next. It collects tasks across projects and lets you filter by project, group, assignee, and completion state.
In practice, use :solid:Tree to organize work and :solid:Todo to execute work. ## :solid:Projects, Groups, and Divisions Projects are the main containers in Termin. A project can stand alone or be placed inside a division. Divisions are sidebar organization labels, such as research areas, teaching, administration, or sponsor categories. Use groups when a project has meaningful internal structure. For example: * A paper project might have groups for `Simulations`, `Figures`, `Manuscript`, `Coauthor Review`, and `Submission`. * A student research project might have groups for `Onboarding`, `Literature`, `Implementation`, `Validation`, and `Writing`. * A class project might have groups for `Lectures`, `Assignments`, `Exams`, and `Grading`. You can drag projects, groups, and divisions to reorganize the sidebar and tree. Right-click project, group, or division headers for actions such as rename, duplicate, delete, move, color, share, or promote. {% hint style="warning" %} Deleting a project, group, or task removes its working context. Prefer renaming, moving, completing, or archiving through project organization unless you are sure the item is no longer needed. {% endhint %} ## :solid:Creating Work Create work directly where it belongs: 1. Open :solid:Tree. 2. Create or select the relevant project. 3. Add groups if the project has structure. 4. Use the `New task...` row in a project or group table. 5. Add a due date, assignee, status mode, description, links, or comments as needed. For quick capture, it is acceptable to create a task first and refine it later. Do not wait for a perfect project structure before recording real work. ## :solid:Tasks A good Termin task should be specific enough that the assignee can tell when it is done. Prefer task names that start with an action verb: * `Draft introduction paragraph on loading protocol` * `Run mesh convergence case for 128 x 128 grid` * `Send travel reimbursement receipt` * `Review Figure 3 caption` Avoid vague task names: * `Paper` * `Simulation` * `Look at this` * `Stuff for Friday` Each task can include:
:solid:TitleThe short action statement that appears in tables and todo lists.
:regular:DueNo date, a specific date, ASAP, or a date relative to another task.
:solid:StatusOpen, critical, complete, percentage complete, multi-user status, or poll response state.
:solid:AssignOne or more users or email collaborators responsible for the task.
:solid:DescriptionLonger instructions, context, Markdown, and MathJax when useful.
:solid:LinksURLs related to the task, project, or group.
:solid:AttachmentsFiles that need to stay with the task context.
:regular:DiscussionComments, decisions, questions, and update history.
## :solid:Task Settings Open the task settings drawer with the :solid:button beside a task. This is where most advanced task behavior lives. Use settings for: * changing task type between a normal task and a poll task; * choosing a status mode; * assigning users, collaborators, project members, or group members; * adding prerequisites; * setting start dates and due behavior; * locking a task after it should no longer be edited; * changing calendar and notification behavior. The drawer also contains the task discussion and, for poll tasks, poll configuration. ### Setting an Assignee and Status Mode
:user: Single StatusThe entire task is either :circle-o: open, :triangle-exclamation: critical, or :circle-check: complete. If there is more than one assignee, any of them may change the status of the task.
:users: Multi-StatusEach user individually sets a personal status for the task. This makes sense for tasks like "Review and approve manuscript" or "Submit travel authorization".
:percent: PercentageSimilar to single status but allows any user to specify a percentage rather than a discrete status. This makes sense when working on tasks in the Gantt chart view.
:square-poll-vertical: PollThe task asks assigned users to choose from a configured set of options. This makes sense for scheduling, approvals, preferences, and lightweight decisions.
Use the simplest status mode that accurately describes the work. Most tasks should be :user:Single Status. Use :users:Multi-Status only when each assignee must independently finish the task. ## :regular:Dates and Planning Termin supports several due-date patterns.
:regular:No DateThe task is tracked but not scheduled. Use sparingly, because undated work is easy to ignore.
:regular:DateThe task is due on a specific calendar date.
:solid:ASAPThe task should be treated as urgent even without a precise date.
:solid:RelativeThe task is due a specified number of days before or after another task.
Relative dates are useful for project plans with dependencies. For example, `Send draft to coauthors` might be due two days after `Finish first complete manuscript draft`. If a project has a start date and end date, Termin can show a Gantt-style planning view. Percentage status works well in that view because it communicates progress without forcing a binary complete/not-complete state. ## :solid:Assignments and Collaborators Tasks can be assigned to Termin users or to outside collaborators by email. When an outside collaborator is assigned, Termin can send a link that lets them view and update their assigned task without needing full project access. Assignment badges show who is responsible and whether an emailed assignment link has been sent, accepted, or denied. Use assignees intentionally: * Assign a task to the person who is expected to act. * Use followers when someone needs awareness but is not responsible. * Use group or project-member assignment when everyone in a defined group must respond. * Avoid assigning a task to many people if only one person owns the next action. ## :solid:Teams and Sharing Teams are reusable groups of Termin users. Create a team when the same people need access to several projects. Projects can be shared with individual users or with teams. Shared users can see the project in Termin and participate according to the access they are given. Use teams for stable groups, such as: * a research subgroup; * a class staff team; * a proposal writing group; * a recurring collaboration. Do not use teams as a substitute for task assignment. Sharing gives access. Assignment creates responsibility. ## :solid:Direct Spaces Direct spaces are one-on-one project spaces. They are useful when two people need a private shared task list without creating a full research project. Common uses include: * advisor-student follow-up; * weekly one-on-one action items; * private reminders between two collaborators; * small administrative exchanges that still need tracking. Direct spaces can contain the same kinds of tasks, due dates, comments, and statuses as regular projects. ## :regular:Discussion and History Use the :regular:discussion button to keep task-specific conversation attached to the work. Comments support Markdown-style writing and user mentions. Discussion is better than email when: * the comment only matters in the context of the task; * a decision should remain visible to future project members; * the task status depends on a question or clarification; * you need a record of what changed and why. Termin also records update history for many changes, such as status, assignment, due date, title, project, group, and description edits. This makes it easier to understand how a task reached its current state. ## :solid:Notifications Termin can notify users about comments, assignments, task updates, project sharing, and related activity. Notifications appear inside the app, and browser push or email notifications may be available depending on your account settings. Use notification settings to control how much Termin interrupts you. A reasonable default is: * keep assignment and mention notifications enabled; * keep comment notifications enabled for active projects; * reduce email frequency if you already check Termin regularly; * use pinned notifications for items that should remain visible until handled. If notifications seem missing, check browser permission settings, account notification preferences, and whether you are assigned to or following the relevant task. ## :solid:Poll Tasks A poll task asks assignees to choose from a set of options. Polls can allow one response or multiple responses. Results can be visible to everyone or limited depending on the poll settings. Polls are useful for: * scheduling a meeting time; * choosing between manuscript title options; * collecting approval from multiple people; * asking group members to select a preferred task, date, or resource. Use a poll task when the real work is a decision or response. Use a normal task when the real work is an action. ## :solid:Prerequisites Prerequisites define task dependencies. If a task depends on another task, add the earlier task as a prerequisite. Termin can show dependent tasks as blocked until prerequisites are complete. Good prerequisite examples: * `Plot final stress-strain curves` depends on `Finish production simulations`. * `Send paper to coauthors` depends on `Complete Figure 2`. * `Submit reimbursement` depends on `Receive hotel receipt`. Do not create dependencies for every small ordering preference. Use prerequisites when completing the later task before the earlier one would be genuinely wrong or confusing. ## :solid:Locked Tasks Lock a task when its content should no longer change casually. This is useful for finalized decisions, completed review records, or tasks that are being used as stable prerequisites. Locked tasks should still be understandable from their title, description, links, and discussion. Add any missing context before locking. ## :solid:Links and Attachments Projects, groups, and tasks can store links. Use links for resources that live elsewhere: * Overleaf projects; * GitHub repositories, issues, and pull requests; * Google Drive folders; * manuscripts, forms, or shared documents; * HPC job pages or dashboards; * relevant papers and references. Attachments are better for files that should be preserved with the task itself. Links are better for living resources that will continue to change. ## :brands:GitHub Sync If your GitHub account is connected, Termin can sync assigned GitHub issues and pull requests into a Termin project. GitHub items are grouped by repository and include links back to GitHub. This is useful when code review, bug fixes, and software tasks should appear beside research and writing tasks. Treat the GitHub-linked Termin task as a tracking mirror; use GitHub for the technical discussion that belongs in the issue or pull request. ## :brands:Calendar Integration Termin can create calendar events for tasks with due dates when calendar integration is enabled. This is most useful for deadline-driven work and external collaborators who rely on calendar invitations. Calendar behavior depends on account connection and opt-in settings. If a task does not appear on a calendar, check: * whether the task has a due date; * whether the relevant user or collaborator opted in to calendar events; * whether a Google account is connected; * whether the task was created before calendar settings were enabled. ## :solid:Group Templates Group templates let you reuse common task lists. They are useful for recurring workflows, such as onboarding a student, preparing a paper submission, setting up a simulation campaign, or running a class module. Use templates for repeated structure, not for one-off plans. A good template contains tasks that are likely to appear every time the workflow occurs. ## :solid:Finding Work Use the Todo view and filters to narrow the active task list. Useful filters include: * only tasks assigned to you; * only tasks in a selected project, group, direct space, or team area; * incomplete tasks; * tasks by due date or urgency. In the Tree view, use project and group structure to find the source context. In the Todo view, use filters to decide what to do next. ## :solid:Suggested Workflows ### Weekly Research Meeting 1. Open the student's direct space or research project. 2. Review incomplete tasks from the previous week. 3. Mark finished work complete. 4. Add new tasks during the meeting. 5. Assign each task and give it a due date when appropriate. 6. Use comments for decisions that should remain attached to the task. ### Paper Management 1. Create a project for the paper. 2. Add groups for major work areas, such as simulations, figures, manuscript, coauthor review, and submission. 3. Link the Overleaf project, repository, Drive folder, and important references. 4. Use prerequisites for tasks that block later work. 5. Use multi-status tasks for coauthor review and approval. 6. Use comments to record decisions about scope, figure choices, and submission plans. ### Proposal or Deadline-Driven Project 1. Set project start and end dates. 2. Add groups for major deliverables. 3. Use due dates and relative due dates for backward planning. 4. Use the Gantt view when the schedule matters. 5. Assign each deliverable to a clear owner. 6. Review the Todo view regularly for overdue and ASAP work. ### Group Request or Decision 1. Create a poll task. 2. Assign the relevant users or group members. 3. Add a clear question and options. 4. Choose whether multiple responses are allowed. 5. Use the discussion for context or follow-up. ## :solid:Good Termin Hygiene Termin works best when the group keeps tasks clear and current. * Create tasks for real work, not vague intentions. * Put tasks in the right project or group before they become hard to find. * Assign a task only when someone is responsible for action. * Use due dates for work that is actually time-sensitive. * Close the loop by marking completed tasks complete. * Add links instead of asking people to search old messages. * Use comments for decisions and context that future readers will need. * Avoid using one giant task as a substitute for a project or group. ## :solid:Troubleshooting
ProblemWhat to check
I cannot see a project.Confirm that the project was shared with your Termin account or with a team you belong to. Also check whether you are looking in Tree, Todo, Direct, or Teams.
A task is not in my Todo view.Check filters, assignee selection, completed-task visibility, project selection, and whether the task is assigned to you or only shared with you.
I cannot edit a task.The task may be locked, you may not have permission for that project or group, or you may be viewing a shared project with limited access.
A due date looks wrong.Check whether the task uses a fixed date, ASAP, or a relative due date. Relative dates depend on another task.
Notifications are missing.Check browser notification permission, Termin notification preferences, assignment/follower state, and whether the relevant task or project is shared with you.
A calendar event did not appear.Check that the task has a due date, the user or collaborator opted in to calendar events, and the relevant Google account is connected.
A collaborator cannot open a link.Resend the assignment link and confirm that it was sent to the correct email address. If the collaborator has a Termin account, make sure the email matches their account or verified email.
## :solid:When Not to Use Termin Termin is not meant to replace every tool.
Use this insteadWhen
:brands:GitHubFor code review, technical issue discussion, pull-request history, and repository-specific decisions.
:solid:Overleaf or DocsFor writing the actual manuscript, proposal, lecture notes, or document text.
:solid:Data repositoriesFor storing simulation data, publication results, and reproducibility artifacts.
:solid:ChatFor ephemeral conversation that does not need to remain attached to a task.
:solid:EmailFor formal external communication, official notices, and communication with people who cannot use Termin links.
The useful pattern is to use Termin as the coordination layer: it should point to the right repository, document, data location, or external conversation and make clear what action is needed next. # Server Access {% hint style="warning" %} Most of this is old and no longer relevant. {% endhint %} Group servers are accessed using Secure Shell, usually called SSH. You must be on the appropriate campus network or connected through VPN before you can access internal servers. ## Windows 1. Download and install PuTTY from [putty.org](http://www.putty.org/). 2. Open PuTTY. 3. Enter the server hostname, such as `servername.uccs.edu`. 4. When prompted, enter your username. 5. When prompted, enter your password. You can also include the username in the hostname: ``` username@servername.uccs.edu ``` Linux systems do not display password characters while you type. This is normal. ## macOS or Linux Open a terminal and run: ```bash ssh servername.uccs.edu ``` or: ```bash ssh username@servername.uccs.edu ``` When prompted, enter your password. The terminal will not display password characters while you type. ## Change Your Password After logging in for the first time, change your password immediately: ```bash passwd ``` Enter your current password, then enter your new password twice. After this, set up public-key authentication using [SSH Public Keys](/computing/ssh-public-keys). # SSH Public Keys Public keys let you use SSH without typing your server password every time. ## Generate a Key On your local machine, run: ```bash ssh-keygen ``` Press Enter to accept the default location. You may enter a passphrase or leave it blank. This creates a `.ssh` directory in your home directory containing files similar to: ``` id_rsa id_rsa.pub ``` The private key, `id_rsa`, must not be shared. The public key, `id_rsa.pub`, can be shared. ## Install the Public Key on a Server Log in to the server, then create the `.ssh` directory and set its permissions: ```bash mkdir .ssh chmod 700 .ssh cd .ssh ``` Create or open a file named `authorized_keys` and paste the contents of your public key into it. Then set the file permissions: ```bash chmod 600 authorized_keys ``` Log out and log back in using SSH. If you created the key with a passphrase, enter it when prompted. Otherwise, you should be logged in without typing your server password. # Ubuntu Group Packages {% hint style="warning" %} Most of this is depricated and needs to be updated or removed. {% endhint %} Group packages are managed through personal package archives and can be installed with the Ubuntu package manager. ## Add Package Archives To add the LaTeX packages archive and group codes archive: ```bash sudo add-apt-repository ppa:solidsuccs/latexpackages sudo add-apt-repository ppa:solidsuccs/codes sudo apt update ``` ## Search for Packages ```bash apt search solidsuccs ``` Example results include: ``` solidsuccs-course Install course Latex class file solidsuccs-presentation Install a beamer template for the Solids research group solidsuccs-reader Templated library of header files to do input file parsing ``` ## Install Packages Use `apt install`: ```bash sudo apt install solidsuccs-presentation sudo apt install solidsuccs-course sudo apt install solidsuccs-reader ``` # ISU VPN on Ubuntu 24.04 The Cisco AnyConnect software is not supported on Ubuntu 24.04. Use OpenConnect through NetworkManager to connect to the Iowa State VPN. These instructions are specific to Ubuntu 24.04 and may not work on earlier Ubuntu versions. ## Install Packages Install OpenConnect and the NetworkManager integration: ```bash sudo apt install network-manager-openconnect network-manager-openconnect-gnome ``` ## Create the VPN Connection Open the network manager and navigate to VPN connections. Add a VPN connection and select Cisco AnyConnect or the equivalent OpenConnect option. ![NetworkManager VPN setup](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-fb5349ef5ad8dcdd46e8a5da6b910c6dd2f2a91d%2Fimage.png?alt=media) ## Set VPN Properties Use the following settings: * VPN Protocol: `Cisco AnyConnect or OpenConnect` * Gateway: `vpn.iastate.edu` * User Agent: `AnyConnect Linux_64 4.7.00136` VPN connection properties ## Connect Activate the VPN. In the authentication dialog, select `Secondary` under `GROUP`. ![VPN group selection](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-ba870936701b21dc3b29eae9fd778ae99445eea7%2Fimage-3.png?alt=media) The OKTA login dialog should open in-window. ![OKTA login dialog](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-3ae4772424ea5d4acf3dcbbd3c436f1437a17baa%2Fimage-4.png?alt=media) Enter your credentials and 2FA information, then connect. The client should indicate successful authentication. ![Successful VPN connection](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-3ba3db21c2cef528f4101895a41c011c3c06eab5%2Fimage-5.png?alt=media) # Python on Windows {% hint style="warning" %} This is old and kind of dated and should probably be cleaned or replaced. {% endhint %} ## Option 1: Google Colaboratory Google Colaboratory is the preferred option for many course and research-adjacent Python tasks. Go to [Google Colab](https://colab.research.google.com/) to create an interactive Python Jupyter notebook. ## Option 2: WinPython and Spyder If you need to run Python locally on Windows, you can use Spyder through WinPython. 1. Download [WinPython](https://winpython.github.io/). 2. Install it on your PC. 3. Open the Spyder application. Spyder provides a script editor and an output panel. ![Spyder on Windows](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-a9b2d2f17e19bf1d5f3f8fc1d33e4bf38f0cb5df%2Fspyder-1024x611.png?alt=media) ## Plotting Example: sin(x) Use the following code to plot a simple trigonometric function: ```python import numpy import pylab X = numpy.linspace(0, 1, 100) Y = numpy.sin(2 * X * numpy.pi) pylab.plot(X, Y) pylab.show() ``` To save a figure instead of showing it interactively: ```python # pylab.show() pylab.savefig(r'C:\Users\brunnels\Desktop\myfile.png') ``` The output format is determined by the file extension. ## Plotting Example: Singularity Brackets The following script plots functions using singularity brackets by defining a `bracket` function. ```python import numpy import pylab def bracket(x, n): return 0.5 * (numpy.sign(x) + 1) * (x**n) L = 1 X = numpy.linspace(0, 2, 1000) Y0 = bracket(X - L, 0) Y1 = bracket(X - L, 1) Y2 = bracket(X - L, 2) pylab.plot(X, Y0, label="^0") pylab.plot(X, Y1, label="^1") pylab.plot(X, Y2, label="^2") pylab.legend() pylab.show() ``` Example output: ![Singularity bracket plot](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-80c199570db7346af8b9b22d4b2f345e51593041%2FUntitled.png?alt=media) # Getting Started with Zephyr [Zephyr](https://zephyr.solids.group) is the Solid Mechanics Group's workspace for tracking Alamo simulations. It records where and how a simulation ran, monitors active jobs, keeps the Alamo metadata and thermodynamic history, and provides a place to organize and share selected results. Zephyr has two parts: * **The web interface** at [zephyr.solids.group](https://zephyr.solids.group), where you browse runs, monitor jobs, compare results, and organize projects. * **The `zph` command-line client**, which connects Alamo output on a workstation or cluster to Zephyr. {% hint style="warning" %} Seeing a run in Zephyr does **not** mean its large raw dataset has been uploaded or archived. Zephyr stores provenance, monitoring data, and files explicitly uploaded with `zph put`. Continue to use the group's [data-management and archival practices](/research-practices/data-management) for large `cell` and `node` datasets. {% endhint %} ## 1. Install `zph` `zph` supports Python 3.7 or newer and has no runtime package dependencies. Install it from the copy hosted by Zephyr: ```bash python3 -m pip install --user --upgrade \ 'https://zephyr.solids.group/downloads/zph-latest.tar.gz' ``` If this is a system Python installation, make sure the user-level binary directory is on your `PATH`: ```bash export PATH="$HOME/.local/bin:$PATH" ``` Add that line to `~/.bashrc` if it is needed every time you log in. Confirm the installation: ```bash zph --version ``` Inside an activated virtual environment or Conda environment, omit `--user` from the installation command. To install a newer version later, run: ```bash zph --upgrade ``` ## 2. Connect Alamo to Zephyr Add `--zephyr` to the normal Alamo configuration command. For example: ```bash ./configure --get-eigen --zephyr https://zephyr.solids.group ``` The configure script asks `zph` to display a temporary login URL and attempts to open it automatically. Sign in using your group Google account. When working over SSH on a cluster, copy the displayed URL into a browser on your own computer. The terminal will continue automatically after authentication succeeds; there is no token to paste. Authentication is stored in your user configuration, not in the Alamo source tree or simulation directories. Repeat this step on each workstation or cluster account that needs to post runs. {% hint style="info" %} If Alamo is already configured, or if you only need to reconnect the CLI, run `zph login https://zephyr.solids.group` directly. {% endhint %} ## 3. Post a simulation Add the boolean `--post` option when starting Alamo: ```bash ./bin/alamo-2d-g++ --post input ``` Use the executable and input file appropriate for your build. In a Slurm script, the same option goes on the Alamo command: ```bash srun --mpi=pmix ./bin/alamo-3d-g++ --post input ``` Alamo starts a lightweight `zph` sidecar. While the solver runs, the sidecar sends heartbeats and refreshes the run status, metadata, `thermo.dat`, standard output, Git revision, and Git diff. Zephyr failures do not stop the simulation itself. Open [zephyr.solids.group](https://zephyr.solids.group) after the run begins. A Slurm run should appear in **Running jobs** with its job name, job ID, cluster, partition, resources, output directory, and current standard output. The **Runs** view retains the record after the job finishes. ## 4. Add simulations that already exist To register one completed output directory: ```bash zph import output.481516 ``` To discover and register every Alamo output below a path: ```bash zph add /scratch/$USER/alamo-runs ``` Wildcards are supported: ```bash zph add 'output*' ``` `zph add` recognizes a run by the `HASH` in its `metadata` file. It safely skips the large numbered BoxLib `cell` and `node` trees during recursive discovery. Its output identifies records as added, updated, skipped, or failed. To preview discovery without changing Zephyr, use: ```bash zph add --dry-run /scratch/$USER/alamo-runs ``` ## 5. Record where copies are stored Use `zph sync` when a simulation directory has been copied, moved, or changed: ```bash zph sync /scratch/$USER/alamo-runs ``` This updates Zephyr's inventory of known locations, paths, file counts, and whether a location contains Alamo simulation data. It does **not** upload the files. Zephyr retains older known locations and the last time each copy was updated. On shared systems, Zephyr uses `SLURM_CLUSTER_NAME` when available. You can provide a stable site name yourself: ```bash export ZEPHYR_SITE=nova zph sync /scratch/$USER/alamo-runs ``` A normal sync avoids descending into expensive BoxLib data trees. Use `zph sync --deep PATH` only when you specifically need an exact scan of every file and byte. ## 6. Upload useful artifacts Use `zph put` for selected files that should be viewable and recoverable from Zephyr, such as plots, animations, processed tables, input files, or postprocessing scripts: ```bash zph put output.481516/plot.png zph put 'output.481516/images/**/*.png' zph put '*.png' '*.webm' '*.gif' ``` For each file, `zph` searches upward for the nearest Alamo `metadata` file. Artifacts in subfolders retain their relative paths. For example, `output.481516/images/frame.png` is stored as `images/frame.png` for the run described by `output.481516/metadata`. You can explicitly associate files with a run directory when necessary: ```bash zph put --directory output.481516 figures/summary.png ``` Images, GIFs, and WebM movies can be previewed in the web interface. In a run's **Artifacts** view, select a representative image or movie as its thumbnail. {% hint style="warning" %} Do not use `zph put` as a substitute for archiving large raw Alamo output trees. Upload the compact files needed for understanding, comparing, sharing, and reproducing a result; archive large datasets using group storage. {% endhint %} ## 7. Organize runs in the web interface The main views are: * **Dashboard:** recent projects, active jobs, and uncategorized runs. * **Runs:** search metadata, paths, and artifact filenames; filter by status, storage site, thumbnail, or uncategorized state. * **Running jobs:** monitor active Slurm jobs and inspect their current standard output. * **Compare:** compare metadata and overlay compatible run data. * **Projects:** arrange runs into folders, browse project artifacts, and share a coherent collection of simulations. In the Runs view, use `Ctrl`-click (or `Command`-click on macOS) to select individual runs and `Shift`-click to select a range. Choose **Add to project** to add one or more selected runs. You can create a project or nested destination folder without leaving the dialog. Inside a project, drag selected runs into folders. Folder open/closed state is remembered in the browser. Project visibility can be private, group-wide, or public; use private visibility until you intentionally want others to have access. ## 8. Restore a run Download a run using its original output-directory name, Alamo `HASH`, or Zephyr run ID: ```bash zph get output.481516 ``` If the directory name is ambiguous, `zph` presents a list of matching runs. If the destination already exists, it offers safe rename, alternate-path, merge/overwrite, and cancel choices. For non-interactive use: ```bash zph get output.481516 --rename zph get HASH --output /work/$USER/restored-run zph get HASH --dry-run ``` The restored directory contains the run record and the artifacts that were actually stored in Zephyr. Raw files that were only inventoried with `zph sync` are not downloaded. ## Useful commands ```bash zph list --status running zph list --search ignition zph compare HASH_A HASH_B zph --upgrade ``` Run `zph COMMAND --help` for all options. ## Troubleshooting ### `zph: command not found` Check the installation and your `PATH`: ```bash python3 -m pip show zph export PATH="$HOME/.local/bin:$PATH" ``` ### The cluster cannot open a browser This is expected on many login nodes. Copy the URL printed by `configure` or `zph login` into a browser on your local computer. Leave the terminal command running while you authenticate. ### A run does not appear Confirm that: 1. `zph` is installed and available on the compute node's `PATH`. 2. This cluster account has been authenticated. 3. The Alamo command includes `--post`. 4. The output directory contains a `metadata` file with a `HASH`. You can register or refresh the output afterward with: ```bash zph add output.481516 ``` ### A file does not upload The file must either be below a directory containing Alamo `metadata`, or you must supply the run directory explicitly: ```bash zph put --directory output.481516 /path/to/file.png ``` Use `--dry-run` first when testing a broad wildcard. # Alamo on HPC This page provides reference information for compiling and running Alamo on high-performance computing (HPC) clusters. > These instructions are for reference only and may not always work. The Alamo developers do not manage the software on these clusters, and configurations may change over time. If you encounter outdated instructions, [open an issue on GitHub](https://github.com/solidsgroup/Alamo/issues). ## Reference Scripts for Nova > For more information on Nova or HPC in general, Iowa State University provides an [online HPC guide](https://www.hpc.iastate.edu/guides). The following environment modules are required to complete the listed tasks. | Task | Required Module(s) | | -------------------------------------- | ------------------ | | Configuring with gcc | `openmpi gcc` | | Configuring with clang | `openmpi llvm` | | Compiling with gcc | `openmpi gcc` | | Compiling with clang | `openmpi llvm` | | Running Alamo | `openmpi gcc` | | Saving data in h5 format (recommended) | `hdf5` | The scripts below automatically handle module management. The configuration and compilation scripts below can be run line-by-line or in a Bash script. If you use a script, make the file executable: ```bash chmod +x /path/to/file ``` > As of April 2025, the git installation on Nova is quite old and can occasionally cause fatal errors when configuring. If you get an error about SSL when the configure script tries to check out AMReX, load the git module with `module load git`. ### GCC Configure and Compile Script ```bash #!/usr/bin/env bash module purge module load openmpi gcc ​module load hdf5/1.14.6-openmpi4-2sb6n2k ./configure --get-eigen --comp=g++ --hdf5 --hdf5-prefix /opt/rit/el9/20240815/app/linux-rhel9-x86_64_v3/gcc-11.4.1/hdf5-1.14.6-2sb6n2kw36egzn3nsgv5uw4wv4c3pgkd srun --nodes=1 --cpus-per-task=16 --mem-per-cpu=1G --time=10:00 make -j16 ``` As of July 28, 2026 compiling with clang does not work on nova, must compile with g++ ### Alamo Simulation Slurm Job Script ```bash #!/usr/bin/env bash #SBATCH --time=24:00:00 #SBATCH --nodes=1 #SBATCH --ntasks-per-node=36 #SBATCH --mem-per-cpu=1000 #SBATCH --job-name="alamo" #SBATCH --output="%x-%j-log.txt" #SBATCH --mail-user=your_email@iastate.edu #SBATCH --mail-type=BEGIN #SBATCH --mail-type=END #SBATCH --mail-type=FAIL module purge module load openmpi srun --mpi=pmix ./path/to/alamo/executable /path/to/input/file ``` The script starts a parallel job on Nova. Modify these parameters as needed: * `--time`: the wall clock time limit, or maximum job duration * `--nodes`: number of nodes requested * `--ntasks-per-node`: number of tasks per node * `--cpus-per-task`: number of cores per task * `--mem-per-cpu`: memory allocated per core, in MB * `--job-name`: job name displayed by `squeue` * `--output`: log filename; see the [Slurm documentation](https://slurm.schedmd.com/sbatch.html#SECTION_FILENAME-PATTERN) for filename pattern specifications * `--mail-user`: email for notifications; remove this if not needed * Executable path: for example, `./bin/alamo-2d-clang++` * Input file path: the input file for Alamo > Iowa State University provides a [Slurm job script generator for Nova](https://www.hpc.iastate.edu/guides/nova/slurm-script-generator-for-nova), which can help generate job scripts. Nova uses a fair-share scheduling system to prioritize job execution based on requested resources and past usage. To reduce wait times, request only necessary resources and set reasonable time limits. Slurm automatically determines the number of cores based on the `--nodes` and `--ntasks-per-node` values. Refer to the [Nova hardware guide](https://www.hpc.iastate.edu/guides/nova) for appropriate values. Once modifications are made, submit the job with [`sbatch`](https://slurm.schedmd.com/sbatch.html): ```bash sbatch /path/to/job_script.sh ``` ## Managing Dependencies on an HPC Cluster Compiling and running Alamo on an HPC cluster differs slightly from doing so on a local machine, primarily because of dependency management. HPC clusters often provide multiple versions of software dependencies for users. To manage these dependencies efficiently, HPC clusters commonly use [Environment Modules](https://modules.sourceforge.net/), or modules, which help users load and unload software as needed. Most HPC clusters provide the required modules for compiling Alamo. To load an environment module: ```bash module load module_1 module_2 ... ``` To unload an environment module: ```bash module unload module_1 module_2 ... ``` To unload all modules: ```bash module purge ``` While Environment Modules are widely used, another tool called [Spack](https://spack.readthedocs.io/en/latest/index.html) was specifically developed for dependency management in shared computing environments. You may encounter either system while working on an HPC cluster. The instructions on this page assume Environment Modules. ## Configuring Alamo on an HPC Cluster Configuring Alamo on an HPC cluster is similar to configuring it on a local machine. However, you must ensure that a compiler, `clang`, and Python 3 are available via modules or other means. Additionally, Alamo relies on the [Eigen library](https://eigen.tuxfamily.org/index.php?title=Main_Page), which can either be loaded as a module or installed during configuration with the `--get-eigen` flag: ```bash ./configure --get-eigen ... ``` Using `--get-eigen` is preferred. ## Compiling Alamo on an HPC Cluster Compiling code can be resource-intensive and time-consuming. Running large, multithreaded operations on the [login node](https://www.hpc.iastate.edu/guides/introduction-to-hpc-clusters/what-is-an-hpc-cluster) of an HPC cluster is generally discouraged. To avoid this, compile within an interactive job or by submitting a batch job. If the cluster uses the [Slurm Workload Manager](https://slurm.schedmd.com/overview.html), an interactive job can be started with [`salloc`](https://slurm.schedmd.com/salloc.html): ```bash salloc --nodes=1 --cpus-per-task=16 --mem=16G --time=10:00 ``` This command requests a single node with 16 cores and 16 GB of memory for 10 minutes. Once the resources are allocated, your shell will reload, and you can compile with: ```bash make -j16 ``` Replace `16` with the number of cores requested. Alternatively, if interactivity is not required, submit a non-interactive compilation job using [`srun`](https://slurm.schedmd.com/srun.html): ```bash srun --nodes=1 --cpus-per-task=16 --mem=16G --time=10:00 make -j16 ``` Adjust resource requests as needed. To reduce wait times, specify a shorter duration using the `--time` flag. ## Running Alamo on an HPC Cluster To verify that a simulation starts correctly, an interactive job may suffice. For full simulations, submit a batch job to the cluster's workload manager. For Slurm-based clusters, use [`sbatch`](https://slurm.schedmd.com/sbatch.html) to submit a job script: ```bash sbatch /path/to/job_script ``` The sections above include example job scripts that can be modified to suit your needs. # GPU Compilation on Nova ## Steps 1. Load the following modules: ```bash module load git openmpi cuda ``` 2. Check out the Alamo repository: ```bash git clone https://github.com/solidsgroup/alamo.git ``` For this workflow, check out the `gpu` branch: ```bash git checkout gpu ``` 3. In the Alamo directory, configure with: ```bash ./configure --get-eigen --cuda ``` The Nova `eigen` module will not work for this workflow. 4. Compile the currently working example: ```bash make bin/heat ``` Optionally start an interactive compilation session to speed up the build: ```bash srun --partition=interactive --pty bash ``` The modules must be reloaded inside the interactive session. You may need to run `make` more than once; the old wiki noted odd issues when compiling in parallel. 5. With Alamo compiled, start a new interactive session: ```bash srun --partition=interactive --gres=gpu:a100:1 --pty bash ``` Load CUDA: ```bash module load cuda ``` 6. Run: ```bash ./bin/heat-3d-cuda80-g++ tests/HeatConduction/input ``` The old wiki reported that this did not work because `libcuda.so.1` could not be found. Symlinking to the `/stub` library was attempted, but the stub library could not be used. # Running Alamo with Python Alamo supports a general Python interface. This is useful for testing functions and models; it is not intended to replace the input file system. ## Clean If this is your first time building the Python interface, run: ```bash make realclean ``` Some build options for the debug version are different. ## Configure Run the configure script with: ```bash ./configure --debug ``` Currently only `g++` is supported because of an issue in AMReX. ## Build the Alamo Library and Python Files Build with: ```bash make py ``` This generates the `setup.py` scripts with paths appropriate for your system. ## Install Use `pip` to install: ```bash pip install -e /path/to/your/alamo ``` You need to have Python development files available. If `pip` complains that it cannot find `Python.H`, you probably do not have the development files installed. ## Run You should now be able to run the following in a Python environment: ```python import alamo ``` Make sure that you do not also have a folder or file named `alamo.py`. This is an easy naming conflict to create. You can include specific header files with: ```python alamo.include("Model/Propellant/PowerLaw.H") ``` Access elements from those files with: ```python model = alamo.Model.Propellant.PowerLaw() ``` All routines and member variables should be accessible. Header files are interpreted, which means changes to headers appear immediately in your Python script without recompiling. If you change code in `.cpp` files, run `make lib` or `make py` again to see those changes. # GitHub Integration with Slack After adding the GitHub app to Slack, configure different channels within the Slack workspace to show GitHub notifications as desired. When you subscribe to notifications on a given Slack channel, the notifications may only be shown to you, not to the other members of the channel. More details are available in the [GitHub Slack integration configuration documentation](https://github.com/integrations/slack#configuration). Enter these commands in the following channels to get the appropriate notifications: | Slack channel | Command | | -------------- | ----------------------------------------------- | | `alamo-commit` | `/github subscribe solidsgroup/alamo commits:*` | | `alamo-issues` | `/github subscribe solidsgroup/alamo issues` | To subscribe to other notifications, either add them to the existing channels or add them directly to the GitHub channel that appears when you add the app. # Common Errors This is a running log of common Alamo error messages, their causes, and fixes.
MLLinOp: grids not coarsenable between AMR levels This is a conflict in the multigrid solver because the grid size is not a power of 2. Fix this by changing the domain dimensions, `amr.n_cell`, so that they are powers of two.
static_cast<long>(i) < this->size() failed One common reason this happens is that Dirichlet or Neumann boundaries are specified but no boundary values are provided.
error: lvalue required as left operand of assignment This can happen when using the `()` operator with an `Isotropic` `Matrix4`-type object. Because this data structure only stores two constants, it is not possible to define any of the values using indices. Similarly, you cannot set an `Isotropic` 4-matrix to a `Cubic` 4-matrix because the cubic matrix has lower symmetry. If you get this error, use a lower-symmetry 4-matrix.
Inconsistent box arrays This is known to happen when using an `Operator::Elastic` inside an `Integrator`, for example in `TimeStepBegin`. Typically this happens when the elastic operator is not initialized within the routine in which it is used. One example is declaring it as a member variable inside an `Integrator`-derived class. The reason is that there are AMReX-specific functions that only get called by the constructor. Fix this by initializing the operator object inside the routine in which it is used. Either make the member variable a pointer and use the `new` keyword, or create the variable inside the function.
MLMG converges in serial but diverges in parallel MLMG sometimes fails to converge in VoronoiElastic in parallel, even if it converges just fine in serial. This generally seems to appear at a C/F boundary (see figure below). \ \ Note that the solution actually appears to be just fine, it’s just that the residual persists. Also note that this only happens when there is a variable model, like in polycrystal elasticity.\ Also, keep in mind that the residual persists whether in parallel or in serial, it’s just that convergence fails in parallel only. So it seems this is a communication issue, not an actual parallel convergence issue. **Fix**: this is also a temporary fix, mostly, and that is to just increase amr.blocking\_factor. In this particular case it was 4 and I increased it to 8. The reason why this makes some sense is that it seems the residual issue occurs when there are two fine patches separated by a very narrow course patch (as in the figure above). Increasing the blocking factor reduces that effect - and in fact, it actually doesn’t hurt performance much either.
MLMG fails to converge Many things can cause failure of convergence. Here are some of the causes and fixes. * One of the issues that can cause problems with MLMG is if a regrid operation occurs and there is a C/F boundary at the domain boundary. The cause appears to be that regridding can do odd things to the RHS fab. For instance, in the process of averaging, some of the RHS stuff can leak from the boundary into the interior. This obviously causes problems. * **Fix**: a temporary appears to be to simply zero out and re-initialize the RHS fab before doing an elastic solve.
# VisIt Tips on how to get running with Visit ## Installing visit on Ubuntu Get Visit here: Download the latest version for which your version of Ubuntu is supported. Note that it often will not work if your version of Ubuntu is too new. The tarball (.tgz) is recommended. where you must change the path (the red part) to whatever path you Extract and put in a common location (usually /opt). The executable is in {extracted path}/bin/. You can add it to your shell by putting the following in your `./.bashrc` file: ``` export PATH=${PATH}:/opt/visit3_3_3.linux-x86_64/bin/ ``` where you must change the path to match whatever the unzipped tarball was. ## Visit on Nova [The Gist](https://gist.github.com/mcmehrtens/8ff559da75699f5084e89e7aeab9549a) has files and scripts to build VisIt and connect to VisIt with client-server, serial/parallel mode. ### Version Support These scripts and configurations have been tested with VisIt **3.4.2** built with the following environment modules: | Software | Version | | -------- | --------------------- | | gcc | 14.2.0-cuda12-vx6uhdf | | openmpi | 4.1.6-jd5jqt4 | | libtool | 2.4.7-cmddukv | | expat | 2.6.3-73vqnat | | git | 2.47.0-hy4cypr |
All environment modules loaded ``` Currently Loaded Modules: 1) libiconv/1.17-pdnbqbs 21) libedit/3.1-20230828-ziky75n 2) xz/5.4.6-xbpkfgh 22) libxcrypt/4.4.35-x6xdydt 3) zlib-ng/2.2.1-4rxbcvx 23) openssh/9.7p1-bcpncex 4) libxml2/2.10.3-6ujajfv 24) ucx/1.17.0-cp7fonc 5) cuda/12.4.1-cz3ljd3 25) openmpi/4.1.6-jd5jqt4 6) gmp/6.3.0-ag5gd7k 26) findutils/4.9.0-53nrqrw 7) mpfr/4.2.1-coqqwdx 27) libtool/2.4.7-cmddukv 8) mpc/1.3.1-uzqwyku 28) libmd/1.0.4-dwc5q6s 9) zstd/1.5.6-qfc7cs2 29) libbsd/0.12.2-vn3dd6q 10) gcc/14.2.0-cuda12-vx6uhdf 30) expat/2.6.3-73vqnat 11) rdma-core/48.0-wp5qvyu 31) nghttp2/1.63.0-h7jonug 12) libfabric/1.21.0-47d4rok 32) curl/8.8.0-vcz5nyl 13) numactl/2.0.16-xzha46m 33) pcre2/10.44-fxqjqnn 14) bzip2/1.0.8-jxv7h7d 34) libunistring/1.2-gqiej3l 15) ncurses/6.5-55fd2mx 35) libidn2/2.3.7-5yea6hh 16) pigz/2.8-edkwki4 36) berkeley-db/18.1.40-zfcwoxv 17) tar/1.34-dimfnd7 37) readline/8.2-g32sjp4 18) gettext/0.22.5-zik5ihu 38) gdbm/1.23-exqbrui 19) openssl/3.3.1-5v6rl3q 39) perl/5.40.0-l2sxfqz 20) krb5/1.21.2-xrjw5a4 40) git/2.47.0-hy4cypr ```
### Building Edit the `build-visit.sh` script below as follows: * Add your email address to the `--mail-user` field. * Set `VISIT_ROOT` to the directory VisIt should be installed to. Run `sbatch build-visit.sh` to build VisIt. I've run into an issue where the VisIt build will fail occasionally because it can't find the Python include directory. Running the build job again usually resolves this issue. {% hint style="warning" %} For more information, refer to VisIt's [build instructions](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/building_visit/Basic_Usage.html) and [advanced build instructions](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/building_visit/Advanced_Usage.html). {% endhint %} ### Configuring Shell When you use VisIt in client-server mode, it first must spin up a metadata server and several other background processes on the server. To do so, VisIt must be able to resolve the OpenMPI library that was used to build VisIt. Since it is currently [impossible to run commands immediately after the SSH session is established](https://github.com/visit-dav/visit/issues/18883), we need to run any necessary commands in your remote shell's startup files. Add the following code to your remote shell's startup file (normally `.bashrc`). This code may need to be modified for non-Bash shells. ```bash # if the shell is not interactive if [[ $- != *i* ]]; then GROUP_OPT=/work/brunnels/opt # load modules required for client-server VisIt module purge module load gcc/14.2.0 openmpi/4.1.6 libtool/2.4.7 expat/2.6.3 git/2.47.0 export PATH="$GROUP_OPT:$PATH" if [ -d $GROUP_OPT ]; then for dir in "$GROUP_OPT"/*/bin; do if [ -d "$dir" ]; then export PATH="$dir:$PATH" fi done for dir in "$GROUP_OPT"/*/lib; do if [ -d "$dir" ]; then export LD_LIBRARY_PATH="dir:$LD_LIBRARY_PATH" fi done fi fi ``` ### Configuring VisIt Download the `host_isu_nova.xml` file from this Git gist. This file is a [*host profile*](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/using_visit/ClientServer/Host_Profiles.html#host-profiles) which VisIt uses to configure the remote server. Put this file in [VisIt's host profile directory](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/using_visit/Preferences/File_Locations.html#host-profile-files). For macOS, this directory is `~/.visit/hosts`. You will need to set a couple parameters of the host profile for your own installation. These can be set [in the GUI](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/using_visit/ClientServer/Host_Profiles.html) or by directly editing the `.xml` file. * `userName`: set to your username on the remote server * `directory`: set to the root VisIt directory (this is `$VISIT_ROOT` in `build-visit.sh`) Once configured, follow the [VisIt documentation to connect via a host profile](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/using_visit/ClientServer/Host_Profiles.html). If you have problems connecting, you may need to [configure passwordless SSH](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/using_visit/ClientServer/Client_server_mode.html#setting-up-password-less-ssh) or [start VisIt from the command line with the `-nopty` option](https://visit-sphinx-github-user-manual.readthedocs.io/en/v3.4.2/getting_started/Startup_Options.html#startup-options). ## Visit tips and tricks
Suppressing warnings and error dialogs Visit's warning/error dialog messages are obnoxious and excessive. To hard-suppress them during a session, open Controls -> Command and execute 
SuppressMessages(1)
You can pass 2 instead of 1 to suppress warnings only. (Even then, some errors will make it though - visit is quite persistent. But it should be a little less intrusive.)
# Paraview with Alamo and HDF5 With the HDF5 capability of Alamo, we can now visualize results using Paraview rather than VisIt (although we can still use VisIt if that is your preference). However, there are some nuances: * When opening .h5 files via the GUI, files that should be grouped in a "time series" are opened individually, thus each time step has its own pipeline for filters, etc. * Vector variables are not automatically defined based on `x/y/z` suffixes, so each directional variable is only accessible as scalar quantities. In order to assist with these limitations, below is a python script that will force the grouped .h5 files to load in a single time series and will automatically search for variables with `x/y/z` suffixes and build corresponding vector variables for them. The script can used by either passing it as an argument if opening Paraview from the command line or as a macro within the GUI itself. ## Command line option To run the script from the command line, **first enter the directory containing the Alamo output** file you wish to visualize. `cd /path/to/celloutput.visit` Then, assuming Paraview is accessible in `PATH` , simply open with the `--script` flag followed by the path to the Python script. `paraview --script /path/to/paraview_load_alamo.py` ## Macro option To run the script as a macro, first open Paraview **from the directory containing the Alamo output** file you wish to visualize. ``` cd /path/to/celloutput.visit paraview ``` and from the top menu select **Macros->Import new macro...** Locate the Python script and select **Ok.** Then once again from the top menu, select **Macros->paraview\_load\_alamo** ## paraview\_load\_alamo.py {% code expandable="true" %} ```python from paraview.simple import * import re import sys # ------------------------------------------------------------ # Read Chombo file list from celloutput.visit # ------------------------------------------------------------ output = "celloutput.visit" files = [] with open(output, "r") as f: for line in f: line = line.strip() if line and not line.startswith("!"): files.append(line) # ------------------------------------------------------------ # Create Chombo reader # ------------------------------------------------------------ reader = VisItChomboReader(FileName=files) reader.UpdatePipelineInformation() # ------------------------------------------------------------ # Enable all available cell variables # ------------------------------------------------------------ all_cell_arrays = [] try: cell_array_info = reader.GetProperty("CellArrayInfo") if cell_array_info is not None: all_cell_arrays = [ cell_array_info.GetElement(i) for i in range(cell_array_info.GetNumberOfElements()) ] except Exception as e: print("CellArrayInfo unavailable:") print(e) # Fallback if len(all_cell_arrays) == 0: print("Using CellArrayStatus fallback") status = reader.GetProperty("CellArrayStatus") all_cell_arrays = [ status.GetElement(i) for i in range(status.GetNumberOfElements()) ] if len(all_cell_arrays) == 0: raise RuntimeError("No cell arrays found") reader.CellArrayStatus = all_cell_arrays reader.UpdatePipelineInformation() # ------------------------------------------------------------ # Detect vector components # # Supports: # velocityx velocityy velocityz # solid.momentumx solid.momentumy solid.momentumz # # Also supports: # velocity.x velocity.y velocity.z # solid.momentum.x ... # ------------------------------------------------------------ vectors = {} for name in all_cell_arrays: # Case 1: suffix x/y/z m = re.match(r"^(.*)(x|y|z)$", name) if m: base, component = m.groups() vectors.setdefault(base, {})[component] = name continue # Case 2: suffix .x/.y/.z m = re.match(r"^(.*)\.(x|y|z)$", name) if m: base, component = m.groups() vectors.setdefault(base, {})[component] = name vector_defs = {} for base, comps in vectors.items(): if "x" in comps and "y" in comps: vector_defs[base] = comps # ------------------------------------------------------------ # Chain Calculator filters # ------------------------------------------------------------ current_input = reader for vec_name, comps in vector_defs.items(): calc = Calculator( Input=current_input, AttributeType="Cell Data", ResultArrayName=vec_name ) if "z" in comps: calc.Function = ( f'iHat*"{comps['x']}" + ' f'jHat*"{comps['y']}" + ' f'kHat*"{comps['z']}"' ) else: calc.Function = ( f'iHat*"{comps['x']}" + ' f'jHat*"{comps['y']}"' ) current_input = calc # ------------------------------------------------------------ # Enable animation # ------------------------------------------------------------ animation = GetAnimationScene() animation.UpdateAnimationUsingDataTimeSteps() timekeeper = GetTimeKeeper() # ------------------------------------------------------------ # Convert cell data to point data # ------------------------------------------------------------ current_input = CellDatatoPointData(Input=current_input) current_input.UpdatePipeline() display = Show(current_input) display.Representation = "Surface" SetActiveSource(current_input) Render() ``` {% endcode %} # ParmParse ## Selector The `pp.select` automates the selection of polymorphic objects by instantiating the object (using either static dispatch or dynamic dispatch) and relaying the parser to the model's `Parse` function. For example: ``` pp.select("phase_field", value.model); ``` sets `value.model` to either `Model::AllenCahn` or `Model::CahnHilliard` depending on what is set in `phase_field.type`. The string that is matched is set as the `name` field in the corresponding class, for example, ``` public: static constexpr const char* name = "allencahn"; ``` indicating that an input value of `phase_field.type = allencahn` will relay to the Allen Cahn integrator, and any subsequent arguments will be given the `allencahn` prefix (e.g. `phase_field.allencahn.mobility=1` ). ### Argument forwarding Sometimes the model that is selected requires additional arguments upon construction. The `IC::IC` family of classes requires an `amrex::Geometry` argument and optionally a unit. These can be passed in using the `pp.forward_args` function as: ``` pp.select("ic",value.ic,pp.forward_args(value.geom)); ``` {% hint style="warning" %} This is a change introduced by [PR297](https://github.com/solidsgroup/alamo/pull/297). Previously, constructor arguments could be forwarded in simply as additional argument to select, like ``` pp.select("ic",value.ic,value.geom); ``` i.e. without the `pp.forward_args` wrapper. This is no longer supported and will trigger compilation errors; all that you need to do to fix is to add the wrapper and it should compile as before. {% endhint %} # Writing and Presentations Scientific writing is an integral part of research. Use these guidelines when writing reports, manuscripts, proposals, presentations, and working notes. ## Document Titles For documents associated with a specific date, such as conference abstracts, presentations, personal statements, or fellowship materials, use: ``` YYYY_MM_DD_NameOfDocument YYYY_MM_DD_NameOfDocument_Yourlastname ``` Use the effective date of the document. Include your last name only when the document is unique to you, not when working on a collaborative document. For in-progress manuscripts, use: ``` PaperDescriptiveTitleOfPaper ``` Use no spaces, use title case, and start with `Paper`. Do not include version numbers in document titles. Documents should be under revision control through Overleaf, GitHub, or Google Docs. Do not manage group work by emailing document versions. ## Templates Always use official group templates for group-related work. * [Beamer presentation template](https://www.overleaf.com/read/jzhnrntgyytt) * [Manuscript template](https://www.overleaf.com/2559314285hmwxhzzrprqh) * [Thesis template](https://www.overleaf.com/read/jzhnrntgyytt) ## Writing Style Scientific writing should be professional, formal, and succinct. * Use a spell checker and proofread for grammar and sentence structure. * Read text out loud to check whether it flows coherently. * Avoid colloquialisms, figures of speech, and idioms. * Paraphrase references instead of using direct quotes. * Define acronyms the first time they appear, then use them consistently. * Treat equations as part of the sentence and punctuate them accordingly. * Avoid using figure references as grammatical nouns. For example, instead of: ``` The results are shown in Figure 3 and have excellent agreement. ``` write: ``` The results were shown to have excellent agreement (Figure 3). ``` ## LaTeX Formatting All professional writing should be done in LaTeX, either on Overleaf or locally. * Use one sentence per line in the LaTeX source. * Separate paragraphs with a blank line. * Use labels and references for tables, figures, sections, equations, and other numbered objects. Example figure: ```latex \begin{figure} \includegraphics{figures/myexamplefigure.pdf} \caption{This is my example figure} \label{fig:myexamplefigure} \end{figure} ``` Reference it with: ```latex The results are shown to match closely (Figure~\ref{fig:myexamplefigure}). % OK The results are shown to match closely (\cref{fig:myexamplefigure}). ``` Use these label conventions: * `fig:name_of_figure` * `tab:name_of_table` * `eq:name_of_equation` * `sec:name_of_section` and use \cref for automatic and consistent formatting of labels. ## BibTeX Use BibTeX to manage citations. Use the Google Scholar convention for BibTeX entries. The general convention is: ``` lastnameYYYYfirstword ``` Acceptable handles: ``` smith1995analyzing gras2018new yi2019fluid ``` Unacceptable handles: ``` Smith1995 gras-2018-new FluidMechanicsYi2019 ``` ## Scientific Posters For poster design guidance, see the [Caltech scientific poster guide](http://writing.caltech.edu/documents/1132/hwc_poster_-_interactive_worksheet.pdf). # Student Research Guide By Dr. Maycon "Mike" Meier, updated by Caleb Munger This is a comprehensive guide to get new members of the Solids Group up to speed with all the tools we use. It is written under the assumption that the new student does not have prior knowledge of C++, Python, and Linux. Thus, it provides details on very basic usages. For more advanced students, this file may still be useful for quick reference of commands that are not frequently used. All terminal commands provided here assume that you are running a Debian-based version of Linux. Exact commands may vary depending on the Linux distribution, but you should be able to google it. In addition, all commands are highlighted in blue. ## Alamo ### Install If you are new to Linux and git usage, start by making sure your computer has git installed. Open a terminal and type the following command: ``` sudo apt install git; sudo apt update; sudo apt upgrade ``` In addition, you may want to download and run the New Computer script from the Solids Group page, which can be done by using the following command on a terminal: ``` wget https://drive.google.com/file/d/1nJD3Ts8dVNCQsBHgyvVEHIyUtuXlsRsk/view; sudo bash new-computer-configure.sh ``` This file can also be accessed by going to -> Resources -> New computer configure script If you are an Alamo collaborator and have set up ssh keys to your GitHub account: Open a terminal and type ``` git clone git@github.com:solidsgroup/alamo.git ``` If you do not have those privileges: Open a terminal and type ``` git clone https://github.com/solidsgroup/alamo.git ``` ### Configure and Make Alamo has a variety of installation options. By default, it is installed in 3D mode and in production mode (i.e. not in debug mode). Different settings are accessed by adding flags to the configure file before using make. The following is an example of how to configure Alamo to 2D mode, debug mode, and to send a request to install the Eigen library, which is used by some Alamo functions. 1. Navigate to the Alamo folder, assuming you cloned Alamo to your home directory and with \ being your computer name, open a terminal and type: cd /home/\/alamo or cd \~/alamo 2. Type: ./configure --dim 2 --debug --get-eigen While the example shows the use of debug, I recommend leaving that off unless you are trying to debug an error, as this flag will cause Alamo to run slower. Once you are finished configuring Alamo, you need to "Make Alamo" in order to create the binary files and actually be able to run the software. That can be done simply by typing make on the terminal inside the Alamo directory. Note that this process can take a few minutes, and can be accelerated by using parallel processing using the j flag. For example, make -j8 which will run using 8 processors. To know how many processors you can use, check the number of cores available in your machine in the settings, type lscpu on your terminal to get that information. Make sure to always leave at least 2 free cores when running any parallel Alamo computation. ### Test Now that you have successfully installed Alamo, you can proceed to run a test case. There is a variety of working cases for different problems inside \~/alamo/tests. To run one of the tests cases, navigate to the alamo directory (cd \~/alamo) and type the following command: ``` mpirun -np 2 ./bin/alamo-2d-g++ ./tests/Eshelby/input ``` In this example, the flag -np is used to indicate the number of processors to be used for parallel computing (2 in this case). Also, note that the g++ alamo file has 2d in its name. If you did not configure using the flag --dim 2, that file name will have 3d instead. If you configure using the debug flag, the file name will be alamo-2d-debug-g++. To check the name simply navigate to \~/alamo/bin/ and type ls. The input file in Eshelby will generate an output folder in \~/alamo/tests/Eshelby/ and the results can then be visualized using VisIt. ### Input File Alamo is a large code and there is a large amount of inputs that can be provided to perform the desired simulations. Before we talk about how to write an input file, let's briefly review how Alamo handles this input file. First, you need to know which integrator you will be using. Navigate to \~/alamo/src/Integrator to check out the list of integrators that are already been implemented. Most integrators are composed of a .H file and a .cpp file. If you are not familiar with C++, .H files will generally set the scope of variables used in the integrator, without performing any calculations, by simply declaring variables and fields, their data type, and optionally a value. Additionally, the functions that will be used are also declared in the .H, without defining what they do just yet. The following image shows examples of content found inside .H files. ```cpp Set::Field temp_mf; Set::Scalar rho_ap; int mob_ap = 0; Set::Scalar q0 = 0.0; IC::IC* ic_eta; struct{ int on = 0; Set::Scalar Tref = 300.0; model_type model_ap, model_htpb; } elastic; void Advance(int lev, Set::Scalar time, Set::Scalar dt) override; ``` Once these variables are declared, their values can be modified by performing code assignments inside .cpp files, or by parsing values from an input value. To know: * Parsing functions that read from the input file are going to appear in many different files, there is no one parsing .cpp file for all variables. * It is generally good practice to include a parser for all variables that are not directly computed in the code so that the number of times you'll need to recompile the code decreases. * If alamo tries to parse a variable that does not show in the input file, it will skip that line. So it is hardly the case you have too many parsing lines. The following image is an example of how to parse a variable from the input file: ```cpp pp.query("thermal.on", value.thermal.on); pp.query("elastic.on", value.elastic.on); ``` Note that the text in quotes "thermal.on" is the variable name in the input file, while the text after `value.` is the name of the variable in the .H file. They do not have to be the same, although they will normally be. $$\int If you are starting a new integrator, be aware of the following: * For Alamo to identify new integrators, they have to be added to the \~/alamo/src/alamo.cc file. * New integrators will generally inherit from Integrator.H, and thus they should stick to the predefined set of functions inside that class. Now, the writing of an input file consists of a .txt file, where each line is one variable separated by the = sign. To know: * \# can be used to comment out a line * Do **not** use any type of line breaker (such as ; in C++) * Numbers can be parsed in scientific notation (i.e. 1.0e5) * You don't need to discriminate between string and numbers. * If a variable type is int, make sure not to add floating points (i.e. 1.0) Some common variables in most alamo input files: * `alamo.program` = name of the integrator in alamo.cc * `plot_file` = relative path to output files * `timestep` * `stop_time` * `amr.plot_int` = frequency alamo writes to output * `amr.plot_dt` = frequency alamo writes to output * `amr.n_cell` = number of cells in the most coarse level * `amr.max_level` = number of refinement levels * `geometry.prob_lo` = x y z lower values for the base box * `geometry.prob_hi` = x y z upper values for the base box Note that a full list of variables that can be parsed can be found in alamo documentation () and that the input search tool in the documentation is very useful (). The following is an example of a fully working input file content: ```ini alamo.program = mechanics plot_file = tests/Solid/output type=static timestep = 0.01 stop_time = 1.0 amr.plot_dt = 0.1 amr.max_level = 0 # amr parameters amr.n_cell = 4 4 4 amr.blocking_factor = 2 amr.thermo.int = 1 amr.thermo.plot_int = 1 # geometry geometry.prob_lo = 0 0 0 geometry.prob_hi = 1 1 1 nmodels = 1 model1.E = 210 model1.nu = 0.3 solver.verbose = 3 solver.nriters = 1 solver.max_iter = 30 bc.type = tension_test bc.tension_test.type = uniaxial_stress bc.tension_test.disp = (0,1:0,0.1) ``` ### Code Debug Alamo is a large code with thousands of lines, and debugging errors can be a very challenging task. Here are some initial ideas of how to first approach the debugging process. 1. Debug mode: when the code breaks before reaching stop\_time, backtrace files are automatically generated from alamo, in the directory the processes were run from. You'll notice that in production mode, the backtrace files are useless, and do not provide any information about what/where the problem is. If you reconfigure Alamo and compile in debug mode, running the code again with a single core, will generate a single backtrace file that has similar information to Python sigaborts backtrace. Read the file from **bottom to top**, it will often point you to what code line in your code is called to abort the process. 2. Alamo has an integrated utility tool that can be used to plot out values, abort processes, and get other information while running your code. The following is a sample of code lines to check for errors during the run and output useful information: ```cpp tempnew(i,j,k) = etanew(i,j,k) * tempsnew(i,j,k) + (1.0 - etanew(i,j,k)) * thermal.T_fluid; if (isnan(temsnew(i,j,k)) || isnan(temps(i,j,k))) { Util::Message(INFO, tempsnew(i,j,k), "tempsnew contains nan (i=",i," j=",j")"); Util::Message(INFO, temps(i,j,k), "temps contains nan (i=",i," j=",j")"); Util::Abort(INFO); } ``` The util tool also has a parallel version of Message and Abort. ### Compiling errors Because Alamo is built using several libraries, there will often be errors when compiling it for the first time. These errors may change over time based on upgrades in different libraries and of Alamo itself, making it hard to construct a list of debug approaches. However, here is a list of the first steps in debugging first-time compiling errors: * Alamo only works in Linux systems (It does work in WSL); MacOS will attempt to build Alamo but will fail due to missing requirements. * Navigate to \~/alamo/docs/requirements.txt and make sure those libraries are installed. * Linux generally carries openmpi by default, but Alamo requires the use of MPich instead. Make sure to install this library. If using an HPC, make sure to load the mpich module. (on incline you simply need to type "module load mpich"; If it fails due to openmpi being loaded, follow the instruction on screen to swap openmpi with mpich. * Install libpng using: sudo apt install libpng-dev ## VisIt ### Install VisIt documentation page has an installation guide here (). I'll add here a quick walkthrough, for the current stable version of VisIt. Be aware that this version may be outdated by the time you read this document. On a new terminal: {% code overflow="wrap" %} ```bash wget https://github.com/visit-dav/visit/releases/download/v3.3.3/visit-install3_3_3 ; wget https://github.com/visit-dav/visit/releases/download/v3.3.3/visit3_3_3.linux-x86_64-ubuntu20.tar.gz ; chmod +x visit-install3_3_3 ; ./visit-install3_3_3 3.3.3 linux-x86+64-ubuntu20 /opt/visit ; ``` {% endcode %} When prompted, select option 0. Once the installation is complete, you can either create an alias or export the PATH in the \~/.bashrc file. Example: {% code overflow="wrap" %} ``` alias visit="/opt/visit/bin/visit" ``` {% endcode %} Or export PATH=${PATH}:/opt/visit/visit3\_3\_3.linux-x86\_64/bin/ ### Basic Plots Once you completed the installation process, you can run VisIt by typing visit to a terminal (remember to start a new terminal after updating .bashrc so the changes take effect). Alamo will generate either celloutput.visit or nodeoutput.visit (or both) inside the output folder, which can then be read into VisIt. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-a27c5b081b6b82485767e26871ad006af6608ac4%2Fimage29.png?alt=media) You can then add plots using the Add button. There are several ways to plot data in VisIt, but we will normally use the Pseudocolor option for most plots. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-33b7799a055b65ae16590e3fecc86dfa94f239b4%2Fimage8.png?alt=media) ### Contour You will notice that if you plot 2 variables at the same time using Pseudocolors, only the last of them will be displayed. Depending on the type of data you are trying to visualize, it may be convenient to add a contour plot, since this plot will show on top of the pseudocolor plot allowing for more data to be visualized at once. ### Isovolume Isovolume is a VisIt operator that allows you to cut off parts of the domain as you want. It is also an alternative way to visualize the data of two fields simultaneously. An example of this is when using the flame integrator, you may not be interested in the region where eta = 0 (fluid zone), and thus you can display only the "solid" region by using the isovolume to cut off eta < 0.1 while displaying the temperature profile. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-9fe224c757393c2c941c984a16bc2172917722db%2Fimage10.png?alt=media) ### Annotations You'll notice that VisIt plots out a lot of annotation information that can get the screen a bit polluted. While that is not a problem for general data visualization, you may want to clean it up when creating images for papers and presentations. You can use the annotation control panel to fully customize the information that is shown, and also to move, resize, and rename the legend information. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-ba384e412e02383e60a12726d1baade2064079dd%2Fimage28.png?alt=media) ### Expressions Often post processing of results is required. For example temperature is used to find the speed of sound to find the Mach number of a fluid, or stresses may be processed to von Mises stress. This can be done in VisIt by defining expressions. Click the controls tab at the top of the plotting panel, and find the "Expressions" dropdown (Or use `Ctrl+Shift+E`), and this screen should appear. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-8d41f9e9acab66d170f5b699e7b0302ab18c178b%2Fexpressions_blank.png?alt=media) Press new (near the bottom left corner, left of the delete button) to define a new expression. The default is to define a scalar expression (speed, distance, temperature, density, etc.) but vector and tensor expressions can also be defined if necessary by changing the "Scalar mesh variable" dropdown (dropdown is right of Type, in upper middle). After making a new expression type the expression in the editor box, ex: `sqrt(stress_xx^2-stress_xx*stress_yy+stress_yy^2+3*stress_xy^2)`. After naming and defining the expression press "Apply" in the bottom left corner of the expressions window to define the new expression. The new variable can now be plotted and used as necessary. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-ad422cbf65db88be6d107beb34732360ddf20ee9%2Fexpressions_stress.png?alt=media) #### Tips An index of a vector can be taken by using `[]`, For example `sqrt(disp_[0]^2+disp_[1]^2)` returns the displacement magnitude, or `sqrt(gradient(density)[0]^2+gradient(density)[1]^2)` returns the magnitude of the spacial density gradient. If you are unsure of the syntax/name of a function use the "Insert function..." dropdown to view all of the built in math functions. You can use a defined expression in another expression. For example, `stress_von_Mises/1000` can be used to convert the units of stress from Pa to kPa. Scalar data (ex: velocity\_x and velocity\_y) can be turned in vector data by defining a new expression and making a `{velocity_x, velocity_y}` expression. This allows the use of integral curves for streamlines or quiver plots for vector visualization. ### Saving Content You can access the window saving setting by pressing ctrl+shift+o (or going to file -> set save options... ). This function allows you to save the current displayed window in different formats. You can also save .curve files, which are text files that contain the values of certain curves you may be displaying. This can be useful, for example, to get to the location of an interface in each time step, and then process this data on Python to generate other plots. You can also generate movies for the time evolution of the system. There are different ways of doing that, but I recommend saving png shots and then using gifski and ffmpeg to create gifs and movies. To do so, go to file -> save movie, and select the png image format. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-5729f4cd1580a5060890604681056e04e4467d18%2Fimage18.png?alt=media) Now you can create a gif by going to the directory you saved the png images and using the following terminal command: {% code overflow="wrap" %} ``` gifski -o .gif visit*.png ``` {% endcode %} If you don't have gifski installed, you can install it by using `snap install gifski`. ### Python Scripting VisIt has a prompt command (CLI) that allows you to execute Python scripts to perform different actions. This can be useful, for example, when you want to extract some information from a simulation plot that has a lot of samples. You may be testing different combinations of parameters that require you to run Alamo hundreds of times, and then you have to analyze the impact on the result, and doing so for each case would be extremely time-consuming. The first step for writing a Python script is to open VisIt and record your actions inside while adding plots, and doing any other actions that you want to script for. To do so, go to controls -> commands and click record. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-17a8bafb82d025ac20a25732e8d3f02b50c115e7%2Fimage16.png?alt=media) Then, proceed to do the actions you would like to automate (adding plots, operators, changing colors, annotations, etc). When you are done, click stop in the command box and VisIt will create a list of commands. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-3f41317e353f4b5a5b5aefd8840df44130151f22%2Fimage2.png?alt=media) You can now copy those commands to a Python file. Here is a sample of python script: PS: remember to import visit ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-13e2c4817f00b23bd32f3734c6e319b180ec8b21%2Fimage5.png?alt=media) ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-0a2b3aac436be9abd9f2d254f56e7d0eec06aecd%2Fimage6.png?alt=media) Now, you can execute the following command: visit -cli -nw -s pythonfile.py The -nw flag is optional, and stops VisIt from trying to launch a new window. This flag is only necessary if you are running VisIt inside of a machine that can not launch user interfaces, such as an HPC (incline). S = fluid \* eta + air \* (1-eta) ## SimBa Often when running Alamo, you will run large numbers of simulations which will create several output data folders. This will quickly make it difficult to manage and remember the difference between different simulations and whether they are relevant or not. Simba is a utility tool that helps you organize this directory using SQL. After installing and configuring, you will be able to launch a webpage that lists all the simulations and their metadata information. It also allows you to delete bad/unused results and to flag different directories according to some status/information you want. Simba is particularly useful when trying to calibrate variables and when trying to show statistical results from many sets of simulations. ### Install Navigate to the directory where you want to install Simba and clone from the repository: git clone Use pip3 to install simba: pip install -e /path/to/simba Test the installation by typing simba on the terminal. ### Configure and Usage Navigate to the project folder you want to use simba. Use the following command: simba init -i /path/to/alamo Enter the simba folder: cd .simba Open the file data.ini emacs -nw data.ini On the bottom of the page, uncomment these lines: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-7f90ef010610759dd897af07c4ac676a29e51f2a%2Fimage14.png?alt=media) Change the match variable to specify the project folder. If you add it as shown in the picture it will include all output files it finds. Use the following command to have Simba read the files: simba add Use the following command to launch simba: simba web You can now open a browser and navigate to the page that is shown in the terminal: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-d3cd8650b78c203a9caba5d77549535b121875fa%2Fimage21.png?alt=media) The page will look like this: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-f42c8382fb74e25f1f7f72fd74db93fe654440f2%2Fimage22.png?alt=media) Simba has several features for filtering, deleting, and organizing your files. Additionally, you are able to create new columns for variables that are not part of the input, such as the burn rate for flame simulations, which are computed in the post processing of the data. To learn how to do data, check the pack.py file in my GitHub codes repository: You can also use tags for each simulation, by clicking in the simulation hyperlink and editing the tag field: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-1d3437245d62d353eb6a8825ed2b1f783a995bdc%2Fimage3.png?alt=media) ## Incline Module swap openmpi4 mpich/3.3.2-ofi You can get this command updated for the current mpich version by typing module load mpich ### Generating keys ssh-keygen -t -rsa -b 4096 -C "" ### Slurm Text ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-562a9a3bd7ed3ab2b22d5da3bf075f26b7495f6c%2Fimage24.png?alt=media) d ### Transfer data rsync \@login.incline.uccs.edu:/mmfs1/home/\/output ./\/ ## Packed Spheres ### Fixed Radii A python code that solves a packing problem for n spheres with the same radius can be found in my codes repo pack.py. This code does not use an input file, it only requires terminal flags. To run: python pack.py --radius=0.01 --pf=0.3 --seed=1 Where radius is the sphere radius, pf is the packing factor (density), and seed controls the random parameters for reproducibility. Note that the maximum sphere volume in a domain is 63% (this is a mathematical constraint). ### Random Radii Several methods can be used to perform random packing with random radii. The following a good option, as the packing code allows not only for random radii but also to control the overlap of spheres. The code works by assigning a porosity value. Git repository: Reference the code using: I have made small changes to this code to allow for more information to be printed out. You can find my version in the repo SpherePacking.cpp. To compile the code: g++ -o spheres SpherePacking.cpp To run, set up a pack.in input file and run spheres pack.in The pack.in file should look as follows: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-134328ed60907ba73102946a1d360885621bc3df%2Fimage20.png?alt=media) In this example, 400 is the number of spheres, 0.3 is the standard deviation, 0.8 is the initial porosity, 0.4 is the target porosity, the third line is the (x,y,z) domain dimensions, 5 5 5 are the number of cells in each direction, 50000 is the max iter, 1.00005 is the radius scaling factor and 1e-10 is the tolerance. ### BMP Alamo can read images and create a diffuse interface based on the level of contrast. You can create black-and-white images using Inkscape and randomly add the desired shape. After that, you can use GIMP to add a Gaussian blur to the image so that the black-to-white transition will get smoother out. If you want to use an image that was created by someone else and it has less contrast than Black-and-white images, you will need to play around with GIMP's different filters in order to create a smooth transition between the phases. ## Overleaf This section is intended to help you satisfy the group requirements and give some insights on organizing your research folders to reduce struggles. First, I recommend that you immediately start an overleaf project as if you are actively writing a paper. You obviously will not have any content to add to it initially, but this will allow you two things: 1 - Save any and all references you may come across. It is rather easy to find some important information and then never be able to find it again. Since you have the paper project, you can add the references there and write bullet points citing those papers, so it is very easy to track them back when you need them. 2 - Overleaf works as a git repository, so you should git clone it to your computer and perform all simulations inside of the repository following the group folder structure. This will save you from a lot of hassle. To git clone your repo click on menu on the top left corner and select the git option: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-0f8b942a00faed6db6cce1024e9cdc29420eaca0%2Fimage25.png?alt=media) Once you create your project, you will need to add the configure files and the organization folder. * Create a folder called results. * Create a folder called images. * Create a main.bib file. * Create a cas-common.cls file. * Create a cas-sc.cls file. * Create a cas-common.sty file. * Create a .gitignore file. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-75413cbd1090de30e5eb22840f943368fdd4ee74%2Fimage1.png?alt=media) In the images folder, you are only going to add images that are not results. Generally, these are images that you create to support the introduction and methodology sections of your paper. In the results folder, you will create new folders for each individual results case. For example, my paper had a pure ap and a mix ap/htpb cases. Each of those cases had hundreds of simulations, all of which are performed inside the respective folder. The content of the cls and sty files and a structure for the main.tex file can be copied and pasted from here: **IMPORTANT:** Once you clone the repository to your computer, make sure to add a .gitignore file, so that you can control which files get uploaded to the cloud. Overleaf has a limit of 2000 files, and alamo simulations will easily fill that up with unnecessary files. Each simulation only needs the metadata and diff files saved to overleaf to ensure the reproducibility of your results. Here is an example of a .gitignore file: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-b3838f20b3305839fb01a6cefbf00c893d7aa985%2Fimage4.png?alt=media) Finally, remember to adhere to all writing standards described in the solid group page ## Inkscape Inkscape is an open-source vector drawing tool. It can be used to create initial condition domains for Alamo. Alamo can read both BMP and PNG format images as inputs. You can download Inkscape directly from the developer webpage inkscape.org The following is a quick example for a simple rectangular domain with a circle particle. This particle can be both a different material, when used as IC for the phi field, or a void/crack when used as IC for the eta field. Assuming my domain will be 0.2 mm x 0.1 mm, navigate to File -> Document properties... and set the width and height of the front page: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-cad4ad576f64e3ba257ea1129c0a6f2cc3963f36%2Fimage26.png?alt=media) Note that you don't need to set the exact dimensions of your Alamo domain, as the image read will fit the image to the domain, so as long as the proportions are kept, you won't have problems. Next, we will draw using only black and white colors so that the contrast is maximized, and it will be easier for Alamo to read the image properly. Note that the domain background displays as white but will be transparent when you export the image, so you need first to add a white rectangle. I am adding a yellow one for the sake of the example. Use the location and size tools on the top to position the square to occupy the entire domain. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-792f75385d3d07cd320b41a2d7f3525086482d6c%2Fimage11.png?alt=media) Next, add a circle to the image and position as desired. Use the bottom color bar to change colors and remove the borders by setting the stroke paint to none. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-0462b07f1be20a7dc8bb9bd327e6ed46ff10da91%2Fimage13.png?alt=media) Finally, use shift to select all elements, right-click and select "group". Then set the blur in the bottom left corner to 9. Note that the amount of blur will control the interface thickness, which will change the total energy at the interface when running flame, so you may need to adjust this blur. The final image should look like this: ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-dd75bfbbdcf1cc676dfda989b2a2b14222426e60%2Fimage9.png?alt=media) You can then click File -> Export to save it as png. If needed, you can read the svg image into gimp to save it as bmp. ## Flame This section is an intro guide for the Flame solver within Alamo, which performs the regression of Solid propellants. The two main files for this solver are \~/alamo/src/Integrators/Flame.cpp and \~/alamo/src/Integrators/Flame.H Flame.H is where all functions, variables, and fields are initialized, and their default values are set; while Flame.cpp is where all functions and models are implemented. If you are new to C++ it is worth noting that these files are supposed to follow the baseline structure of Alamo, thus two important points are to be made: 1. We generally do not create new functions; rather, we override existing functions from Alamo Integrator.H. The following functions are available in that integrator: 1. Parse() => This is where variables are read from an input file. (PS: This function is called in several files, so not all variables will be read by Flame.cpp). To add a new variable to be read, use the following: 1. pp.query("\ ", value.\); > Note that the name to be read from the input file does not need to match the name inside Alamo, though it generally does. > > Parse is also used to register new fields. Fields are essentially matrices, which will store the value of a variable for all cells or nodes of the solution domain. Beware that some variables can be solved as regular variables or as fields. This decision will impact two things: 1) for you to visualize such a variable with VisIt, it has to be a field. 2) field variables will generally compute more efficiently but at the cost of higher memory usage. It also increases the size of the output files from Alamo, which can grow very quickly (several GBs for large simulations). 2. Initialize() => Once a field is created in Parse, you need to set its value with both the initial and boundary conditions. 3. TimeStepBegin() => This function is called before the model computes the next time step. For flame, this is where the Laser field is added to the model. 4. UpdateModel() => This function is called every n time steps, where n can be defined in the input file. For Flame, this is where the Elastic solver is called. This solver is implemented in \~/alamo/src/Integrator/Base/Mechanics.H \~/alamo/src/Model/Solid/Finite/NeoHookeanPredeformed.H and NeoHookean.H 5. Advance() => This is where most of the Flame model work is implemented. 6. TagCellsForRefinement() => This is where the refinement criteria are implemented, which are based on the gradient (variation) of field variables, subjected to a tolerance that is set in the input file through variables defined in lines 79 - 82 of Flame.H 7. Regrid() => This function applies refinement to the tagged cells and is called every n timesteps, where n is defined in the input file. 8. TimeStepComplete() => This function is called in the end of the process. For Flame this is where the pressure ballistics are implemented. 9. Integrate() => This function is used to perform the integration of variables and fields. This can be used to compute a variable used somewhere else in the code and output information to thermo.dat files. 10. We use a system to name variables so that they are easy to understand: 1. struct { \ } \; 2. Additionally, variables are not defined using the C++ traditional long and double type groups, that is replaced by a Set::Scalar type so that it is standardized. (we still use int and bool types). In the following example, a1 would be called pressure.arrhenius.a1. ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-e8fae7c4abc0e000863b4d73b44c1998b1ffc38b%2Fimage19.png?alt=media) Flame is currently implemented with a few solver options. First, the Elastic solver can be turned on and off by setting the values of elastic.on and elastic.type. Additionally, you can switch between the original solver and the thermal-driven solver using the variable thermal.on (Note that if thermal.on = 0 then you MUST disable the elastic solver by setting elastic.on = 0 and elastic.type = disable). Additionally, the gas phase pressure can be either a constant set value or let free to float using the variable variable\_pressure. The boundary conditions drive the direction of the regression. Here are two examples: * Left to right ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-aeef0e98c941d6b25a1097dbee0851c9bb72831a%2Fimage27.png?alt=media) * Whole regressing outwards ![](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-c06a736b1e3ce97c3cb696e45af76c748db0b1ef%2Fimage7.png?alt=media) ### Questions you should know the answer for I strongly recommend you read the papers we have published in the past few years. The following are important questions that are answered in the papers and that are key to understanding the model: * What other methods have previously been used for the SCP regression problem? What was better about them? What was worse about them? * When should you use Dirichlet boundary condition, Periodic BC, or Neumann BC? * What is the case where Periodic BC can not be used in Flame? * Advantages of the diffuse interface over sharp interface; * Disadvantages of diffuse interface; * What sets phase-field apart from other diffuse interface methods? * Does phase-field need boundary conditions? Where and why? * How does the phase-field interface length scale affect the solution for the eta and phi fields? * How are the chemical potentials defined in Flame formulation? * Why do we need a Laser field? * What is the relationship between mesh refinement and interface length? * Why does the model use a surrogate fluid and stand-in fluid? * What AP/HTPB elastic physical phenomena are not currently captured by the model? * What thermal effects are not currently captured by the model? * What are the key causes of instability? # Data Management This page describes how to organize production, publishable simulation results in a way that supports sponsor requirements, reproducibility, and good scientific practice. ## Data Organization Approach The group uses a paper-oriented data organization strategy. Simulation data should be associated with the publication in which it will eventually appear. This keeps results close to the best available documentation and minimizes time lost when work passes between group members. ## Paper Git Repository Every paper should be under Git version control through Overleaf or GitHub. This applies even if the manuscript itself is written in Word for collaborator or journal reasons. When you are ready to generate potentially publishable results, create the paper repository. Before publication, use this naming convention: ``` PaperDescriptiveTitleMixCapsNoSpaces ``` Examples: ``` PaperElasticSolver PaperMicrostructureEvolution ``` Counterexamples: ``` ElasticSolverPaper Paper_ElasticSolver paperelasticsolver Paper Elastic Solver ``` After publication, rename the repository to match the Google Scholar BibTeX ID, such as `authorlastnameYYYYfirstword`. ## Results Directory Structure Create a `results` directory in the paper repository. Put all simulation data and postprocessing results there. ``` PaperDescriptiveName/ main.tex main.bib figures/ graphic.svg graphic.pdf results/ TypeOne/ README input hpc_batch.sh plotTypeOneStats.py TypeOneStats.pdf output_202310250824/ metadata diff.patch plot_eta.pdf plot_temp.pdf 00000cell/ 00001cell/ outputdata.tar.gz output_202310250825/ output_202310250826/ TypeTwo/ ``` Files in `figures` should be illustrations only, not simulation results. If a figure is editable, include both the editable source, such as an Inkscape SVG, and the rendered file used in the paper. Files in `results` are simulation results. Any figure that contains simulation data must be stored in `results`, as close as possible to the data that generated it. For example: ```latex \includegraphics{results/TypeOne/output_202310250824/plot_eta.pdf} ``` This makes it clear how the visualization was generated. ## Metadata Each simulation directory must contain enough metadata to reproduce the result. For Alamo, include the standard metadata outputs. For other codes, include whatever metadata is needed to recreate the calculation. Metadata files should be version controlled. Raw simulation outputs may be too large for Git. They should still live in the same logical directory, but they should be excluded from version control and moved to archival storage as soon as practical. ## Postprocessing Data Most visualization and postprocessing is done in Python. All postprocessing scripts must be stored in version control. Raw Python scripts and Jupyter notebooks are both acceptable. Postprocessing data should be stored as close as possible to the data being processed: * If a visualization uses one simulation, store it in that simulation directory. * If a visualization uses multiple simulations, store it in the lowest-level directory that contains all relevant simulations. Name scripts so their outputs are obvious. For example, `plot_eta.py` should generate `plot_eta.pdf`. Avoid generic script names such as: ``` analysis.py get_x.py randomfunctions.py ``` Avoid disconnected output names such as: ``` eta.pdf myplot.pdf output.pdf ``` If a project cannot follow the standard organization, add a `README` explaining the structure. Even then, the results directory must contain the information needed to generate the results and the outputs from those results. ## Journal Submission Some journals do not support complex LaTeX directory structures. In those cases, a submission-specific fork may be used to move or rename files for journal requirements. The archival research structure should remain intact. After acceptance, rename the repository according to the BibTeX tag. ## Archiving Most sponsored projects require data archiving. The group uses ISU Large Scale Storage for long-term archival storage. Before archiving, compress large simulation data when possible. For example: ```bash tar cvzf output.tar.gz *cell ``` Store the compressed output in the same simulation folder before transferring it to archival storage. ## Example Workflow Suppose you are working on `PaperLargeDeformationElastic`, which builds on Smith et al. 2015. 1. Find the BibTeX tag for the earlier paper, such as `smith2015novel`. 2. Check out the `smith2015novel` repository from Overleaf or GitHub. 3. In the LaTeX source, find where the relevant figure is generated: ```latex \includegraphics{results/DamageModeling/output.20192930103/plot.pdf} ``` 4. Go to `results/DamageModeling/output.20192930103/` and inspect the metadata. 5. If rerunning the simulation is too expensive, locate the archived file: ``` smith2015novel/results/DamageModeling/output.20192930103/output.tar.gz ``` 6. Copy the archive into the local clone, regenerate the plot using the local postprocessing script, and confirm the result. 7. Copy the needed input files and results into the corresponding folder in your new paper repository. 8. Add a note in the `README` explaining that the results derive from the previous work. Good data organization prevents the original author from becoming a future bottleneck and makes prior work easier to understand, reproduce, and extend. # Paper Organization A hallmark of good scientific computing is simulation reproducibility: computational results should be regenerable when needed. Computational work is difficult and time-consuming, so it is easy to publish results before documenting all the steps needed to obtain them. This page describes how simulation results should be presented in paper repositories. ## Naming convention Paper names (i.e. the repo name on overleaf) should follow the format PaperDescriptiveTitle. For example: :circle-check: :regular:`PaperReactiveFlowComparison`\ :regular::circle-check: `PaperTurbulentJetValidation`\ :regular::circle-check: `PaperShockTubeIgnitionStudy` \ :circle-xmark: `paper-reactive-flow-comparison`\ :regular::circle-xmark: `ReactiveFlowComparison`\ :regular::circle-xmark: `Paper Reactive Flow Comparison` ## Paper Repository Outline This example uses the Alamo convention, but the principles apply to any simulation result. ``` PaperDescription/ main.tex main.pdf main.out figures/ MyFigure.svg MyFigure.pdf results/ TestCaseA/ output1/ input.in metadata diff.patch smalldatafile.dat bigdatafile.dat pressure_profile.pdf output2/ pressure_profile.py comparefigure.pdf TestCaseB/ ``` ## Postprocessing Design plotting scripts so that they are easy for other people to use. Multiple people may create, revise, and regenerate figures during manuscript development and review. Use descriptive filenames: ``` Bad: plot.py Good: thermal_contours.py ``` Do not use absolute file paths: ```python # BAD: not portable data = load_data("/home/brunnels/Research/PaperDescription/results/TestCaseA/output1/bigdatafile.dat") ``` Design scripts to run from the results directory: ```python # GOOD data = load_data("./TestCaseA/output1/bigdatafile.dat") ``` When possible, process large data into smaller files that can be stored in the repository: ```python small_data = process_my_data(bigdata) small_data.save("./TestCaseA/output1/smalldatafile.dat") ``` Then allow users to load the smaller processed data. This makes figures reproducible even when someone does not have access to the full raw dataset. Store plots near their data and give them obvious names. :circle-xmark: `small_data.saveplot("output1.pdf")`\ :circle-check: `small_data.saveplot("./TestCaseA/output1/thermal_contours.pdf")` When possible, give the plot the same name as the output it generates. Use PDF whenever possible unless a raster format is necessary. ## Including Figures in LaTeX Use paths that make the source of the figure clear: ```latex \begin{figure} \includegraphics{results/TestCaseA/output1/thermal_contours.pdf} \end{figure} ``` From the filepath alone, a reader can tell that the figure is a simulation result from `TestCaseA`, in `output1`, showing thermal contours. The corresponding script should be nearby and similarly named. ## Guiding Principles * Every paper is a Git repository. * Simulation data is stored in the associated paper repository. * Data too large for Git should still live in the same directory structure, but should be excluded through `.gitignore`. * Every simulation gets its own self-contained subdirectory. * Each simulation directory should contain everything needed to generate the simulation. * Visualizations should be stored as close to the data as possible. * Scripts should be stored as close to the visualizations as possible and named similarly when practical. * The `figures` directory is for illustrations only, not scientific results. # Travel Guidance Conference and workshop travel is an important part of research. Presenting work and attending talks helps students connect with the broader research community and leaders in their field. This page outlines basic instructions and expectations for student travel. ## Submitting an Abstract Abstract deadlines are often at least two months, and sometimes up to nine months, before a conference. Plan ahead. Before submitting an abstract, get written confirmation from Dr. Runnels that travel funds are available. Abstract requirements vary. Some conferences require only a few hundred words; others require a draft paper. Give yourself enough lead time. Share abstracts with Dr. Runnels using Overleaf or Google Drive. For future work, make a good-faith estimate of where the project will be by the conference date. ## Requesting Student Travel Funding Even when travel is likely funded through a grant, students are expected to pursue available funding opportunities to help cover costs. This helps stretch group travel funds and creates more opportunities for students. Common funding sources include: * Internal university travel funds * Conference travel scholarships or fellowships for graduate students and early-career researchers After submitting an abstract, investigate these options. Send Dr. Runnels an update by email or Slack explaining which opportunities you are applying for, or why you are not eligible. You are not expected to win every fellowship, but you are expected to make a reasonable attempt. ## Creating a Presentation or Poster Plan to have your presentation or poster ready at least two weeks before the conference. Use the group template for all presentations and posters. Templates are available in the Google Slides template gallery when logged in with solids.group credentials. Know the time limit for your talk. Conference talks are usually 15 to 20 minutes including questions, but the conference website should give the exact time. Practice thoroughly. A good rule of thumb is to practice at least 10 times before presenting, especially for a first conference talk. ## Booking Travel Communicate travel plans with Dr. Runnels early, especially if you need to arrive late, leave early, or handle special circumstances. ### Accommodations The group will generally book a hotel at the conference venue. If you arrive before Dr. Runnels, you may need to provide your credit card for incidentals at check-in. Lodging expenses should generally go to the appropriate travel card or university process. ### Conference Registration Students are usually not required to register themselves. Registration is generally handled by the department. If you do need to register yourself, request reimbursement afterward. ### Airfare There are three common ways to book airfare. Book yourself and request reimbursement: This is often easiest, especially if you receive a travel award. If you use this option, request a quote from Christopherson Business Travel (CBT) for your itinerary before booking. Send your itinerary to `trips@cbtravel.com` and ask them to confirm the amount. University policy may limit reimbursement to the quoted amount. Ask CBT to book for you: Send your itinerary to `trips@cbtravel.com`. You can use this option only if you know the speedtype for the trip. Book through Concur: You can book directly through Concur if you have the speedtype. ### Ground Transportation Uber is often used, especially when the conference is in an urban venue and parking is expensive. Save receipts for reimbursement. ### Per Diem You may be eligible for travel per diem depending on the trip type and funding source. Discuss this with Dr. Runnels when planning the trip. ## At the Conference Dress professionally. For men, this generally means dress shoes, slacks, a dress shirt, and a sport jacket. A tie is encouraged but optional. A suit is fine but optional. For women, this means conservative business-appropriate denim, dresses, skirts, blazers, and similar professional attire. Keep conduct professional at all times. You are expected to attend and engage in conference activities. You do not need to attend every relevant talk, but you should review the program and find sessions related to your work. Technical conversations with people you meet are also valuable and encouraged. Use the time well. ## Giving a Presentation You will usually bring your own laptop. Before the session: * Bring suitable adapters. * Charge your laptop. * Have an offline version of the presentation. * Test the presentation without internet. * Arrive early. * Meet the session chair. * Test your equipment. Conference venues often have poor internet or no internet, so do not depend on a live connection. ## Presenting a Poster Set up the poster well before the poster session begins. Be present at the poster during the entire session and be ready to answer questions. Prepare a rehearsed five-minute explanation so you can guide visitors through the work. ## Recreation You are welcome and encouraged to have fun. Conferences are often in good locations, and it is fine to explore, relax, recharge, and get to know people in a less formal setting. ## Reimbursement Reimbursements are processed through the administrative office and usually after the trip has concluded. Send receipts to the office and copy Dr. Runnels on correspondence. If you receive a travel award, request reimbursement from the award source first. If the award comes through the university, it may be processed through financial aid. If it is external, it may arrive as a check. Notify the administrative office so the award amount can be accounted for in reimbursement. ## Cancellation When you commit to present at a conference, you are expected to attend. Cancellations due to illness, family emergency, or similar circumstances are understandable. If a cancellation is not due to a legitimate reason, you may be held responsible for some or all travel costs incurred. # PhD Comprehensive Exam Mechanical Engineering PhD students must follow the department guidelines for the comprehensive exam. This page outlines the process for students in the Solid Mechanics group. ## Overview Treat the comprehensive exam as a dry run for the thesis defense. You should take the exam only when you and Dr. Runnels agree that the bulk of your thesis work is complete. In general, plan to take the comprehensive exam about one year before your defense. You may take it the semester before your defense if you are prepared to complete up to a year of thesis work before defending. ## Timeline ### Several Months Before At least three to four months before the exam, consult with Dr. Runnels to determine whether you are ready and what the timeframe should be. Do not proceed until you and Dr. Runnels are in agreement. Confirm that: * Your finalized Program of Study is complete. * Your committee members are confirmed. ### Two Months Before If any committee members are non-UCCS faculty or UCCS IRC faculty holding the rank of instructor, they may need paperwork for special appointment to the UCCS graduate faculty. Give committee members plenty of time. Committee members, especially those outside the university, are doing you a favor by serving. Be respectful of their schedules and provide lead time on all requests. Determine committee availability and reserve a room. For the comprehensive exam, as with the thesis defense, you are responsible for scheduling and managing the event. Plan for a two-hour reservation block. If the meeting is hybrid, confirm that the room has appropriate equipment and that remote participants have complete joining information. If visitors are joining in person from off campus, ask the department administrator to send parking information or a parking code. ### One Month Before You should have a mostly finalized thesis document and a complete draft ready for Dr. Runnels to review. The thesis should be written in LaTeX on Overleaf using the official template. ### Two Weeks Before Send your thesis to the committee for feedback and remind them of the talk details: time, location, and remote access if applicable. For in-person committee members, print a hard copy if appropriate. Make sure Dr. Runnels has the presentation details so the talk can be advertised to the department. The talk is open, and anyone may attend. ### One Week Before Finalize the presentation and share it with Dr. Runnels if you have not already. Incorporate recommended changes before the presentation. ## Day of the Exam The comprehensive exam usually follows this format: * 10 minutes: arrive and set up * 1 hour: presentation, including questions from the general audience * 30 minutes: private session with you and your committee * 15 minutes: private committee deliberation * 5 minutes: notification of the committee decision ## Two Weeks After Dr. Runnels will ask committee members to submit written feedback on the presentation and thesis. You are responsible for addressing their comments before the thesis defense, just as you would address reviewer comments for a journal article. # Fellowship Opportunities Group students are encouraged to pursue external fellowship opportunities, even if they are already supported through a GRA or grant. Fellowships can provide benefits that standard research assistantships do not, and they strengthen a student's CV. This list is a starting point. Program names, deadlines, eligibility, and benefits change, so verify details on the program website before applying. ## Opportunities [Agency for Science, Technology and Research (A\*STAR)](http://www.a-star.edu.sg/Awards-Scholarship/Overview.aspx) A\*STAR Graduate Academy offers scholarships and fellowships for students pursuing scientific training and R\&D careers. [American Society of Mechanical Engineers Graduate Teaching Fellowships](https://www.asme.org/career-education/scholarships-and-grants/scholarship-and-loans/fellowships/graduate-teaching-fellowships) ASME graduate teaching fellowships support doctoral candidates in mechanical engineering education and related fields. [Argonne National Laboratory Graduate Student Programs](http://www.dep.anl.gov/p_graduate/) Argonne offers graduate student opportunities related to laboratory research programs. [Chateaubriand Fellowships for Science and Technology Research in France](http://stem.chateaubriand-fellowship.org/) The Chateaubriand Fellowship supports doctoral students at American universities who want to conduct part of their research in a French laboratory. [Council of Graduate Schools / ProQuest Distinguished Dissertation Award](http://www.cgsnet.org/cgsproquest-distinguished-dissertation-award) These awards recognize dissertations that make unusually significant contributions to their disciplines. Nomination is through member institutions. [Department of Defense SMART Scholarship](http://smart.asee.org/) The Science, Mathematics, and Research for Transformation program supports STEM students and includes post-degree employment obligations. [DOE Computational Science Graduate Fellowship](https://www.krellinst.org/csgf/) The DOE CSGF supports graduate students whose work combines a scientific or engineering discipline with computer science and applied mathematics. [DOE NNSA Stewardship Science Graduate Fellowship](http://www.krellinst.org/ssgf/about-doe-nnsa-ssgf) The DOE NNSA SSGF supports PhD students working on science and engineering problems relevant to stewardship science. [DOE Office of Science Graduate Student Research Program](http://science.energy.gov/wdts/scgsr/) SCGSR supports graduate thesis research at DOE laboratories in areas relevant to the Office of Science. [DOE Office of Science Graduate Fellowship](http://science.energy.gov/wdts/scgf/) The DOE SCGF has supported graduate study in disciplines relevant to DOE Office of Science mission areas. [Ford Foundation Fellowships](http://sites.nationalacademies.org/PGA/FordFellowships/index.htm) Ford Foundation fellowships are offered at predoctoral, dissertation, and postdoctoral levels. [Fulbright Program for Foreign Students](http://foreign.fulbrightonline.org/) The Fulbright Program supports citizens of other countries pursuing master's or PhD study in the United States. [Gates Millennium Scholars Program](http://www.gmsp.org/) The Gates Millennium Scholars Program supports education costs and graduate study in selected fields for continuing Gates Millennium Scholars. [GEM Fellowship Program](http://www.gemfellowship.org/gem-fellowship) GEM provides MS and PhD fellowships coupled with paid summer internships. [Hertz Foundation Fellowship](http://www.hertzfoundation.org/dx/fellowships/application.aspx) The Hertz Fellowship supports doctoral students in applied physical, biological, and engineering sciences. [IBM PhD Fellowship](http://www.research.ibm.com/university/phdfellowship/index.shtml) The IBM PhD Fellowship recognizes PhD students working in areas important to IBM and related academic disciplines. [Indo-US Science and Technology Research Internships in Science and Engineering](http://iusstf.org/story/53-49-Research-Internships-In-Science-and-Engineering.html) RISE provides research internship opportunities in India for science, technology, engineering, and medical students from the United States. [Intel PhD Fellowship Program](http://www.intel.com/content/www/us/en/education/university/intel-phd-fellowship-program.html) Intel PhD Fellowships support doctoral candidates pursuing fields related to Intel's business and research interests. [Josephine de Karman Fellowship Trust](http://www.dekarman.org/category/fellowship/) The de Karman Fellowship recognizes students whose scholastic achievements reflect high academic standards. [Korea Foundation for Advanced Studies Scholarship](http://www.kfas.or.kr/ScholarShip/ScholarShip0201.aspx) KFAS supports doctoral study at overseas research universities in selected fields. [Lawrence Livermore National Laboratory Graduate Scholar Program](https://lgsp.llnl.gov/) The LLNL Graduate Scholar Program supports PhD students conducting laboratory-relevant research while completing their thesis. [Linda Hall Library Fellowship](http://www.lindahall.org/fellowships/) Linda Hall Library offers resident fellowships for research in science, engineering, technology, and related history or interdisciplinary areas. [Link Foundation Energy Fellowships](http://www.linkenergy.org/index.html) The Link Foundation supports PhD students working on energy production and utilization. [Los Alamos National Laboratory Graduate Research Assistantship](http://www.lanl.gov/careers/career-options/student-internships/graduate/index.php) LANL's Graduate Research Assistant program provides research experience for students pursuing graduate degrees. [Microsoft Research PhD Fellowship](http://research.microsoft.com/en-us/collaboration/awards/apply-us.aspx) Microsoft Research PhD Fellowships support students working in computer science and related areas. [NASA Earth and Space Science Fellowship](http://www.lpi.usra.edu/planetary_news/2013/11/01/nasa-earth-and-space-science-fellowship-nessf-program/) NESSF supports master's and doctoral students in Earth and space sciences and related disciplines. [NASA Soffen Grants for Travel to Conferences](http://soffenfund.org/) Soffen grants support student travel to meetings where applicants present aerospace-related research. [National Defense Science and Engineering Graduate Fellowship](http://ndseg.asee.org/about_ndseg) NDSEG is a portable doctoral fellowship for U.S. citizens and nationals in supported disciplines. [National Research Council Research Associateship Programs](http://www.nationalacademies.org/rap) NRC research associateships support guest researchers at participating federal laboratories and research organizations. [NSF Graduate Research Fellowship Program](http://www.nsfgrfp.org/) The NSF GRFP supports graduate students pursuing research-based master's and doctoral degrees in NSF-supported STEM disciplines. [NSF Graduate Research Opportunities Worldwide](http://www.nsf.gov/pubs/2014/nsf14005/nsf14005.jsp) GROW provides international research collaboration opportunities for NSF Graduate Fellows. [Natural Sciences and Engineering Research Council Scholarships](http://www.nserc-crsng.gc.ca/Students-Etudiants/PG-CS/BellandPostgrad-BelletSuperieures_eng.asp) NSERC scholarships support doctoral students in natural sciences and engineering. [Oak Ridge Institute for Science and Education Fellowship](http://orise.orau.gov/science-education/internships-scholarships-fellowships/default.aspx) ORISE administers internships, scholarships, fellowships, and research project appointments. [Paul and Daisy Soros Fellowships for New Americans](https://www.pdsoros.org/) The Soros Fellowship supports graduate study in the United States for New Americans. [Sandia National Laboratories Master's Fellowships](http://www.sandia.gov/careers/special_programs/masters_fellowships_program.html) Sandia's master's fellowship program supports selected students pursuing technical master's degrees. [Semiconductor Research Corporation Graduate Fellowship Program](https://www.src.org/student-center/fellowship/) SRC offers doctoral fellowships and master's scholarships through several semiconductor research programs. # Remote Exam Protocol This protocol describes a process for administering remote exams without compromising exam integrity. Students should read the instructions carefully before the exam. ## Before the Exam Students should have the following ready before the exam begins: 1. A computer with webcam, Zoom, and internet connection 2. A workspace in full view of the webcam 3. Scratch paper 4. Writing implements 5. Food or beverages, if desired ## Exam Packet Students receive a tamper-evident sealed exam packet in a 10-by-13-inch envelope. For students taking the exam remotely, the envelope includes the student's mailing address, postage, and the department return address. Exams should be sent using certified mail, and tracking numbers should be emailed to students. Students taking the exam in person pick up the exam from the department office during the specified time. Do not open the packet before the exam begins. If the seal is broken before the exam begins, the exam will not be accepted. ![Sealed remote exam packet](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-16a91e40f7d0adaa9d119527f8e69471ee717f2a%2Fremote-exam-1.png?alt=media) The exam packet includes: 1. The exam document 2. One unsealed 9-by-12-inch envelope with the student's name in the return address area 3. One unused tamper-evident seal ![Exam packet contents](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-6bab670f124f2c5ad7134cb2ee3f0d9f50517068%2Fremote-exam-2.png?alt=media) ## Taking the Exam On exam day, complete these steps in order: 1. Log into the Zoom classroom. 2. When instructed, and in full view of the webcam, break the seal on the exam packet and remove the contents. 3. Begin the exam immediately. 4. After the exam, put the exam document and all scratch paper into the inner envelope. ![Exam materials in return envelope](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-2eebf8d7706aaf51fb62ae2867dd70d1b18a2b4e%2Fremote-exam-3.png?alt=media) 5. Seal the exam using the tamper-evident seal. ![Tamper-evident seal on return envelope](https://685164709-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeANVOBYNJa4QbJRfCyTX%2Fuploads%2Fgit-blob-ecd7fbee1d10c73a1f3dfa022bd33f7bd75c3f0a%2Fremote-exam-4.png?alt=media) 6. Show on webcam that the envelope has been sealed. 7. Return the exam to the department office in person or by mail. If returning by mail, the student is responsible for postage. Submission should be postmarked no later than 48 hours after the exam date. ## For Administrators: Preparing the Exam Packet Supplies required, where `N` is the number of students: * `N` 10-by-13-inch packet envelopes * `N` 9-by-12-inch submission envelopes * `2N` tamper-evident seals * `N` exam documents, printed from the instructor-provided PDF * `2N` mailing labels ## Prepare the Packets 1. Print labels for the packet envelopes and place them in the recipient address area. For mailed packets, include the student's address, department return address, and postage. 2. Print labels for the submission envelopes. These should match the packet-envelope labels but be placed in the return address area. 3. Print and staple the exam document. 4. Place the exam document, the unsealed 9-by-12-inch submission envelope, and one unused tamper-evident seal into the packet envelope. 5. Seal the packet envelope with a tamper-evident seal. 6. Mail exams to remote students. 7. Check out exams to in-person students during the arranged time. If you do not know the student, check ID before releasing the exam. ## Send the Exam Packets 1. Print a list of students to mark off exams mailed or released. 2. For students receiving the exam by mail, mail the exam by certified mail no later than two weeks before the scheduled exam date. 3. Send tracking numbers to the instructor so they can be sent to students. 4. For students picking up the exam in person, check out exams during the arranged time and check ID when needed. ## Collect Submission Packets 1. Gather all exams for pickup by the instructor or TA. 2. If an exam is returned late, mark `LATE` and the date and time on the submission envelope. # Codex ## Setting up Codex in your environment Install codex using the command `npm install -g @openai/codex` In recent versions of Ubuntu, there are some extra steps to configure `codex` so that it functions more effectively in the sandbox. More information can be found here: \ \ BLUF: Run these commands to configure `apparmor` to allow `codex` to work correctly in the sandbox. The final command reloads the policies without requiring a reboot. ``` sudo apt update sudo apt install apparmor-profiles apparmor-utils dpkg -L apparmor-profiles | grep bwrap-userns-restrict sudo install -m 0644 \ /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \ /etc/apparmor.d/bwrap-userns-restrict sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict ``` # Visiting Us ### Our Location Our lab is located in [**Howe Hall**](https://maps.app.goo.gl/65M1t58y7q3z1csZ7)**.** ### Air Travel If you are visiting from out of state, the nearest airport is the Des Moines International Airport (DSM), about a 50 minute drive from campus. You can generally get an Uber to and from campus. ### Lodging If you are visiting overnight, the closest lodging option is the [Iowa House](https://iowahouseames.com/) bed & breakfast, about a 15 minute walk from Howe Hall. Other area hotels are listed [on this ISU information page](https://apling.engl.iastate.edu/html/ames-travel/). If you do not have a car, many of the hotels are served by the free CyRide bus routes. ### Parking We recommend parking in one of the metered [ParkMobile](https://parkmobile.io/) locations. Some of the options are listed below (from nearest to farthest). When driving, you can use these links to navigate to the exact location. 1. [Outside Howe Hall](https://maps.app.goo.gl/7WY4FrAFvxxouXGM6) - ParkMobile Zone 7234 2. [Lot 9](https://maps.app.goo.gl/thYrqthYx4AopGEv6) - ParkMobile Zone 2704 3. [Lot 10](https://maps.app.goo.gl/yxJvGp43obZK3tWz7) - ParkMobile Zone 2704 4. [Pammel Drive](https://maps.app.goo.gl/47fRQWfQgy3g6zVG7) - ParkMobile Zone 2704 {% hint style="warning" %} Confirm that your space has a physical parking meter. **Spaces that do not have a parking meter require an ISU parking** and you'll get a ticket if you don't have one. Enforcement is quite strict! {% endhint %}